Add plugin flag argument to enable JSON pretty printing

[lopsae]

Bug/issue #127

Summary

Add the --json-prettyprint flag to enable the output json files to be pretty-printed and ordered. This flag can be used with both generate-documentation and preview-documentation.

Implementation

The docc executable already supports pretty printing by adding the environment variable DOCC_JSON_PRETTYPRINT, as described in the docc contribution guide.

When the —json-prettyprint flag is used, the Process that executes the docc command is updated with the DOCC_JSON_PRETTYPRINT environment property, which enables the feature. Otherwise the inherited environment for the Process is not modified.

Dependencies

No external dependencies.

Testing

For a package configured to generate docc documentation, run the generate-documentation plugin command without --json-prettyprint

swift package --allow-writing-to-directory ./docs \
   generate-documentation \
   --output-path ./docs \
   --disable-indexing \
   --transform-for-static-hosting

Inspecting any of the json files in produced in docs, the contents should be in single line of json without any discernible order, for example docs/index/index.json:

{"includedArchiveIdentifiers":["DoccExtensionsIssue"],"interfaceLanguages":{"swift":[{"children":[{"title":"Structures","type":"groupMarker"},{"children":[{"title":"Instance Properties","type":"groupMarker"}
[...]

Run again using --json-prettyprint:

swift package --allow-writing-to-directory ./docs \
   generate-documentation \
   --output-path ./docs \
   --disable-indexing \
   --transform-for-static-hosting \
   --json-prettyprint

The content of the same json file now should be spaced, for example:

{
  "includedArchiveIdentifiers" : [
    "DoccExtensionsIssue"
  ],
  "interfaceLanguages" : {
    "swift" : [
      {
        "children" : [
[...]

If the same generate-documentation is run again, no output files should have changed in docs.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

Discussion

Swift Forums Discussion.

[lopsae]

@swift-ci please test