From 8945459662a9460526234b603201b20c470bb386 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Tue, 20 Feb 2024 14:44:16 +0100 Subject: [PATCH] Document the supported arguments, flags, and options for DocC's CLI rdar://119262681 --- .../Assets/command-icon.svg | 4 + .../Assets/command-icon~dark.svg | 4 + .../Commands/convert.md | 175 ++++ .../Commands/emit-generated-curation.md | 62 ++ .../DocCDocumentation.docc/Commands/index.md | 32 + .../DocCDocumentation.docc/Commands/init.md | 27 + .../Commands/preview.md | 23 + .../Commands/transform-for-static-hosting.md | 32 + .../DocC Documentation.md | 4 + .../DocCDocumentation.docc/DocC.symbols.json | 764 +++++++++++++++++- .../docc/DocCDocumentation.docc/commands.md | 35 + .../CommandUsageParser.swift | 86 ++ Sources/generate-symbol-graph/main.swift | 132 ++- 13 files changed, 1374 insertions(+), 6 deletions(-) create mode 100644 Sources/docc/DocCDocumentation.docc/Assets/command-icon.svg create mode 100644 Sources/docc/DocCDocumentation.docc/Assets/command-icon~dark.svg create mode 100644 Sources/docc/DocCDocumentation.docc/Commands/convert.md create mode 100644 Sources/docc/DocCDocumentation.docc/Commands/emit-generated-curation.md create mode 100644 Sources/docc/DocCDocumentation.docc/Commands/index.md create mode 100644 Sources/docc/DocCDocumentation.docc/Commands/init.md create mode 100644 Sources/docc/DocCDocumentation.docc/Commands/preview.md create mode 100644 Sources/docc/DocCDocumentation.docc/Commands/transform-for-static-hosting.md create mode 100644 Sources/docc/DocCDocumentation.docc/commands.md create mode 100644 Sources/generate-symbol-graph/CommandUsageParser.swift diff --git a/Sources/docc/DocCDocumentation.docc/Assets/command-icon.svg b/Sources/docc/DocCDocumentation.docc/Assets/command-icon.svg new file mode 100644 index 0000000000..e41b7fa62d --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Assets/command-icon.svg @@ -0,0 +1,4 @@ + diff --git a/Sources/docc/DocCDocumentation.docc/Assets/command-icon~dark.svg b/Sources/docc/DocCDocumentation.docc/Assets/command-icon~dark.svg new file mode 100644 index 0000000000..1d4593095c --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Assets/command-icon~dark.svg @@ -0,0 +1,4 @@ + diff --git a/Sources/docc/DocCDocumentation.docc/Commands/convert.md b/Sources/docc/DocCDocumentation.docc/Commands/convert.md new file mode 100644 index 0000000000..f97b93a89a --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Commands/convert.md @@ -0,0 +1,175 @@ +# ``convert`` + +Convert documentation markup, assets, and symbol information into a documentation archive. + +@Metadata { + @PageImage(purpose: icon, source: command-icon) +} + +## Arguments, Flags, and Options + +### Inputs & Outputs + +- term ``: + Path to the documentation catalog ('.docc') directory. + +- term `--additional-symbol-graph-dir `: + A path to a directory of additional symbol graph files. + +- term `-o, --output-path, --output-dir `: + The location where the documentation compiler writes the built documentation. + +### Availability Options + +- term `--platform `: + Specify information about the current release of a platform. + + Each platform's information is specified via separate `--platform` values using the following format: `name={platform name},version={semantic version}`. + + Optionally, the platform information can include a `beta={true|false}` component. If no beta information is provided, the platform is considered not in beta. + +### Source Repository Options (Swift-DocC 5.8+) + +- term `--checkout-path `: + The root path on disk of the repository's checkout. + +- term `--source-service `: + The source code service used to host the project's sources. Supported values are `github`, `gitlab`, and `bitbucket`. + + Required when using `--source-service-base-url`. + +- term `--source-service-base-url `: + The base URL where the source service hosts the project's sources. For example: `"https://github.com/my-org/my-repo/blob/main"`. + + Required when using `--source-service`. + +### Hosting Options (Swift-DocC 5.6+) + +- term `--hosting-base-path `: + The base path where your will host your documentation. + + For example, if you deploy your site to `example.com/my_name/my_project/documentation` instead of `example.com/documentation`, pass `/my_name/my_project` as the base path. + +- term `--no-transform-for-static-hosting`: + Don't produce a documentation output that supports static hosting environments. + +### Diagnostic Options + +- term `--analyze`: + Include `note`/`information` level diagnostics in addition to warnings and errors. + +- term `--diagnostics-file, --diagnostics-output-path ` **(Swift-DocC 5.9+)**: + The location where the documentation compiler writes the diagnostics file. + + Specifying a diagnostic file path implies `--ide-console-output`. + +- term `--diagnostic-filter, --diagnostic-level `: + Filter diagnostics with a lower severity than this level. + + This option is ignored if `--analyze` is passed. + + This filter level is inclusive. If a level of `note` is specified, diagnostics with a severity up to and including `note` will be printed. + + The supported diagnostic filter levels are: + - `error` + - `warning` + - `note`, `info`, `information` + - `hint`, `notice` + +- term `--ide-console-output, --emit-fixits`: + Format output to the console intended for an IDE or other tool to parse. + +- term `--warnings-as-errors` **(Swift-DocC 5.8+)**: + Treat warnings as errors. + +### Info.plist Fallbacks + +- term `--default-code-listing-language `: + A fallback default language for code listings if no value is provided in the documentation catalogs's Info.plist file. + +- term `--fallback-display-name `: + A fallback display name if no value is provided in the documentation catalogs's Info.plist file. + + If no display name is provided in the catalogs's Info.plist file or via the `--fallback-display-name` option, DocC will infer a display name from the documentation catalog base name or from the module name from the symbol graph files provided via + the `--additional-symbol-graph-dir` option. + +- term `--fallback-bundle-identifier `: + A fallback bundle identifier if no value is provided in the documentation catalogs's Info.plist file. + + If no bundle identifier is provided in the catalogs's Info.plist file or via the '--fallback-bundle-identifier' option, DocC will infer a bundle identifier from the display name. + +- term `--fallback-default-module-kind ` **(Swift-DocC 5.6+)**: + A fallback default module kind if no value is provided in the documentation catalogs's Info.plist file. + + If no module kind is provided in the catalogs's Info.plist file or via the `--fallback-default-module-kind` option, DocC will display the module kind as a "Framework". + +### Documentation Coverage Options (Experimental) + +- term `--experimental-documentation-coverage`: + Generate documentation coverage output. + + Detailed documentation coverage information will be written to `documentation-coverage.json` in the output directory. + +- term `--coverage-summary-level `: + The level of documentation coverage information to write on standard out. (default: `brief`) + + The `--coverage-summary-level` level has no impact on the information in the "documentation-coverage.json" file. + + The supported coverage summary levels are `brief` and `detailed`. + +- term `--coverage-symbol-kind-filter `: + Filter documentation coverage to only analyze symbols of the specified symbol kinds. + + Specify a list of symbol kind values to filter the documentation coverage to only those types symbols. + + The supported symbol kind values are: `associated-type`, `class`, `dictionary`, `enumeration`, `enumeration-case`, `function`, `global-variable`, `http-request`, `initializer`, `instance-method`, `instance-property`, `instance-subscript`, `instance-variable`, `module`, `operator`, `protocol`, `structure`, `type-alias`, `type-method`, `type-property`, `type-subscript`, `typedef`. + + +### Link Resolution Options (Experimental) (Swift-DocC 5.11+) +- term `--dependency `: + A path to a documentation archive ('.doccarchive') directory to resolve external links against. + + Only documentation archives built with `--enable-experimental-external-link-support` are supported as dependencies. + +### Feature Flags + +- term `--experimental-enable-custom-templates`: + Allows for custom templates, like `header.html`. + +- term `--enable-inherited-docs`: + Inherit documentation for inherited symbols. + +- term `--allow-arbitrary-catalog-directories` **(Experimental)** **(Swift-DocC 5.10+)**: + Allow catalog directories without the `.docc` extension. + +- term `--enable-experimental-external-link-support` **(Swift-DocC 5.11+)**: + Support external links to this documentation output. + + Write additional link metadata files to the output directory to support resolving documentation links to the documentation in that output directory. + +- term `--enable-experimental-overloaded-symbol-presentation` **(Swift-DocC 5.11+)**: + Collects all the symbols that are overloads of each other onto a new merged-symbol page. + +- term `--enable-experimental-mentioned-in` **(Swift-DocC 5.11+)**: + Render a section on symbol documentation which links to articles that mention that symbol. + +- term `--enable-experimental-parameters-and-returns-validation` **(Swift-DocC 5.11+)**: + Validate parameter and return value documentation. + + Validates and filters symbols' parameter and return value documentation based on the symbol's function signature in each language representation. + +- term `--emit-digest`: + Write additional metadata files to the output directory. + +- term `--emit-lmdb-index`: + Writes an LMDB representation of the navigator index to the output directory. + + A JSON representation of the navigator index is emitted by default. + +### Other Options + +- term `-h, --help`: + Show help information. + + + diff --git a/Sources/docc/DocCDocumentation.docc/Commands/emit-generated-curation.md b/Sources/docc/DocCDocumentation.docc/Commands/emit-generated-curation.md new file mode 100644 index 0000000000..a76501fdfd --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Commands/emit-generated-curation.md @@ -0,0 +1,62 @@ +# ``emit-generated-curation`` + +Write documentation extension files with markdown representations of DocC's automatic curation. + +@Metadata { + @PageImage(purpose: icon, source: command-icon) +} + +## Overview + +Pass the same `` and `--additional-symbol-graph-dir ` as you would for `docc convert` to emit documentation extension files for your project. + +If you're getting started with arranging your symbols into topic groups, you can pass `--depth 0` to only emit a documentation extension file for the module, organizing the top-level symbols. + +If you want to arrange a specific sub-hierarchy of your project into topic groups you can pass `--from-symbol ` to only write documentation extension files for that symbol and its descendants. This can be combined with `--depth ` to control how far to descend from the specified symbol. + +> Important: +> When you have generated documentation extension files, you should go through the links and move them into new topic groups based on conceptually relevant topics for your project. +> +> Any links that you leave in the generated per-symbol-kind topic groups don't provide any additional organization of your project. + +To help you distinguish between API that you've arranged into topics and API that's automatically grouped by symbol kind, it is recommended to remove all generated per-symbol-kind topic groups that you didn't arrange into new conceptual topic groups. You can always run `emit-generated-curation` again later to iteratively work on arranging your documentation into topic groups. + +For more information on arranging documentation into topic groups, see . + +## Arguments, Flags, and Options + +### Inputs & Outputs + +- term ``: + Path to the documentation catalog ('.docc') directory. + +- term `--additional-symbol-graph-dir `: + Path to a directory of additional symbol graph files. + +- term `--output-path `: + The location where `docc` writes the transformed catalog. + + > Important: If no output-path is provided, `docc` will perform an in-place transformation of the provided documentation catalog. + +### Generation Options + +- term `--from-symbol `: + A link to a symbol to start generating documentation extension files from. + + If no symbol-link is provided, `docc` will generate documentation extension files starting from the module. + +- term `--depth `: + A depth limit for which pages to generate documentation extension files for. + + If no depth is provided, `docc` will generate documentation extension files for all pages from the starting point. + + If 0 is provided, `docc` will generate documentation extension files for only the starting page. + + If a positive number is provided, `docc` will generate documentation extension files for the starting page and its descendants up to that depth limit (inclusive). + +### Other Options + +- term `-h, --help`: + Show help information. + + diff --git a/Sources/docc/DocCDocumentation.docc/Commands/index.md b/Sources/docc/DocCDocumentation.docc/Commands/index.md new file mode 100644 index 0000000000..1ab217525b --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Commands/index.md @@ -0,0 +1,32 @@ +# ``index`` + +Create an LMDB index for an already built documentation archive. + +@Metadata { + @PageImage(purpose: icon, source: command-icon) +} + +If you pass the `--emit-lmdb-index` flag to the ``convert`` command, `docc` will create an LMDB index during the build so that you don't need to process the archive after it's been built. + +## Arguments, Flags, and Options + +### Inputs + +- term ``: + Path to the documentation archive ('.doccarchive') directory to build an LMDB index for. + +### Other Options: + +- term `--bundle-identifier ` **(required)**: + The bundle identifier of the processed archive. + +- term `--verbose`: + Print out the index information while running. + +- term `-h, --help`: + Show help information. + +> Earlier Versions: +> Before Swift-DocC 5.6, the `index` command was a top-level command instead of a `process-archive` subcommand. + + diff --git a/Sources/docc/DocCDocumentation.docc/Commands/init.md b/Sources/docc/DocCDocumentation.docc/Commands/init.md new file mode 100644 index 0000000000..3570665c4b --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Commands/init.md @@ -0,0 +1,27 @@ +# ``init`` + +Create a documentation catalog from a template. + +@Metadata { + @PageImage(purpose: icon, source: command-icon) +} + +## Arguments, Flags, and Options + +- term `--name ` **(required)**: + The base name for the created documentation catalog ('.docc') directory. + +- term `-o, --output-dir ` **(required)**: + The location where the documentation catalog will be written. + +- term `--template ` **(required)**: + The template to use for the created catalog directory. Supported values are: + + - term `articleOnly`: This template contains a starting point for writing article-only reference documentation not tied to an API. + + - term `tutorial`: This template contains the necessary structure and directives to get started with writing tutorials. + +- term `-h, --help`: + Show help information. + + diff --git a/Sources/docc/DocCDocumentation.docc/Commands/preview.md b/Sources/docc/DocCDocumentation.docc/Commands/preview.md new file mode 100644 index 0000000000..0de330d69d --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Commands/preview.md @@ -0,0 +1,23 @@ +# ``preview`` + +Convert documentation inputs and preview the documentation output. + + +@Metadata { + @PageImage(purpose: icon, source: command-icon) +} + +The `preview` command extends the ``convert`` command by running a preview server and monitoring the documentation input for modifications to rebuild the documentation. + +## Arguments, Flags, and Options + +### Preview Options + +- term `-p, --port `: + The port number to use for the local preview web server. (default: `8080`) + +### Convert Options + +The `preview` command supports all the same arguments, flags, and options as the ``convert`` command. + + diff --git a/Sources/docc/DocCDocumentation.docc/Commands/transform-for-static-hosting.md b/Sources/docc/DocCDocumentation.docc/Commands/transform-for-static-hosting.md new file mode 100644 index 0000000000..4e6d988aa4 --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Commands/transform-for-static-hosting.md @@ -0,0 +1,32 @@ +# ``transform-for-static-hosting`` + +Transform an existing documentation archive into one that supports a static hosting environment. + +@Metadata { + @PageImage(purpose: icon, source: command-icon) +} + +@DeprecationSummary { + As of Swift-DocC 5.7, documentation archives support static hosting environments by default. There is no need to call this command anymore. +} + +## Arguments, Flags, and Options + + +- term ``: + Path to the documentation archive ('.doccarchive') directory that should be processed. + +- term `--output-path `: + The location where `docc` writes the transformed archive. + + > Important: If no output-path is provided, `docc` will perform an in-place transformation of the provided documentation archive. + +- term `--hosting-base-path `: + The base path where your will host your documentation. + + For example, if you deploy your site to `example.com/my_name/my_project/documentation` instead of `example.com/documentation`, pass `/my_name/my_project` as the base path. + +- term `-h, --help`: + Show help information. + + diff --git a/Sources/docc/DocCDocumentation.docc/DocC Documentation.md b/Sources/docc/DocCDocumentation.docc/DocC Documentation.md index 1406753cdc..2afe434f67 100644 --- a/Sources/docc/DocCDocumentation.docc/DocC Documentation.md +++ b/Sources/docc/DocCDocumentation.docc/DocC Documentation.md @@ -48,4 +48,8 @@ DocC syntax — called _documentation markup_ — is a custom variant of Markdow - ``Comment`` +### Command line + +- + diff --git a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json index 64eefd8332..78c13a4b84 100644 --- a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json +++ b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json @@ -26,6 +26,736 @@ ], "symbols" : [ + { + "accessLevel" : "public", + "availability" : [ + { + "domain" : "Swift-DocC", + "introduced" : { + "major" : 5, + "minor" : 5, + "patch" : 0 + } + } + ], + "declarationFragments" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "convert" + }, + { + "kind" : "text", + "spelling" : " \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "]\n [" + }, + { + "kind" : "externalParam", + "spelling" : "--additional-symbol-graph-dir" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "externalParam", + "spelling" : "--output-dir" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "]" + } + ], + "identifier" : { + "interfaceLanguage" : "swift", + "precise" : "__docc_universal_command_reference_$convert" + }, + "kind" : { + "displayName" : "Command", + "identifier" : "class" + }, + "names" : { + "subHeading" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "convert" + }, + { + "kind" : "text", + "spelling" : " ..." + } + ], + "title" : "convert" + }, + "pathComponents" : [ + "convert" + ] + }, + { + "accessLevel" : "public", + "availability" : [ + { + "domain" : "Swift-DocC", + "introduced" : { + "major" : 5, + "minor" : 11, + "patch" : 0 + } + } + ], + "declarationFragments" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "process-catalog" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "emit-generated-curation" + }, + { + "kind" : "text", + "spelling" : " \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "externalParam", + "spelling" : "--additional-symbol-graph-dir" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "externalParam", + "spelling" : "--output-path" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "externalParam", + "spelling" : "--from-symbol" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "externalParam", + "spelling" : "--depth" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "]" + } + ], + "identifier" : { + "interfaceLanguage" : "swift", + "precise" : "__docc_universal_command_reference_$emit-generated-curation" + }, + "kind" : { + "displayName" : "Command", + "identifier" : "class" + }, + "names" : { + "subHeading" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "process-catalog" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "emit-generated-curation" + }, + { + "kind" : "text", + "spelling" : " ..." + } + ], + "title" : "emit-generated-curation" + }, + "pathComponents" : [ + "emit-generated-curation" + ] + }, + { + "accessLevel" : "public", + "availability" : [ + { + "domain" : "Swift-DocC", + "introduced" : { + "major" : 5, + "minor" : 5, + "patch" : 0 + } + } + ], + "declarationFragments" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "process-archive" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "index" + }, + { + "kind" : "text", + "spelling" : " \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n " + }, + { + "kind" : "externalParam", + "spelling" : "--bundle-identifier" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : " \\\n [" + }, + { + "kind" : "externalParam", + "spelling" : "--verbose]" + } + ], + "identifier" : { + "interfaceLanguage" : "swift", + "precise" : "__docc_universal_command_reference_$index" + }, + "kind" : { + "displayName" : "Command", + "identifier" : "class" + }, + "names" : { + "subHeading" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "process-archive" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "index" + }, + { + "kind" : "text", + "spelling" : " ..." + } + ], + "title" : "index" + }, + "pathComponents" : [ + "index" + ] + }, + { + "accessLevel" : "public", + "availability" : [ + { + "domain" : "Swift-DocC", + "introduced" : { + "major" : 5, + "minor" : 11, + "patch" : 0 + } + } + ], + "declarationFragments" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "init" + }, + { + "kind" : "text", + "spelling" : " \\\n " + }, + { + "kind" : "externalParam", + "spelling" : "--name" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : " \\\n " + }, + { + "kind" : "externalParam", + "spelling" : "--output-dir" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : " \\\n " + }, + { + "kind" : "externalParam", + "spelling" : "--template" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + } + ], + "identifier" : { + "interfaceLanguage" : "swift", + "precise" : "__docc_universal_command_reference_$init" + }, + "kind" : { + "displayName" : "Command", + "identifier" : "class" + }, + "names" : { + "subHeading" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "init" + }, + { + "kind" : "text", + "spelling" : " ..." + } + ], + "title" : "init" + }, + "pathComponents" : [ + "init" + ] + }, + { + "accessLevel" : "public", + "availability" : [ + { + "domain" : "Swift-DocC", + "introduced" : { + "major" : 5, + "minor" : 5, + "patch" : 0 + } + } + ], + "declarationFragments" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "preview" + }, + { + "kind" : "text", + "spelling" : " \\\n [" + }, + { + "kind" : "externalParam", + "spelling" : "--port" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n [" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "]" + } + ], + "identifier" : { + "interfaceLanguage" : "swift", + "precise" : "__docc_universal_command_reference_$preview" + }, + "kind" : { + "displayName" : "Command", + "identifier" : "class" + }, + "names" : { + "subHeading" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "preview" + }, + { + "kind" : "text", + "spelling" : " ..." + } + ], + "title" : "preview" + }, + "pathComponents" : [ + "preview" + ] + }, + { + "accessLevel" : "public", + "availability" : [ + { + "domain" : "Swift-DocC", + "introduced" : { + "major" : 5, + "minor" : 6, + "patch" : 0 + } + } + ], + "declarationFragments" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "process-archive" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "transform-for-static-hosting" + }, + { + "kind" : "text", + "spelling" : " \\\n[" + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n[" + }, + { + "kind" : "externalParam", + "spelling" : "--output-path" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "] \\\n[" + }, + { + "kind" : "externalParam", + "spelling" : "--hosting-base-path" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "typeIdentifier", + "spelling" : "" + }, + { + "kind" : "text", + "spelling" : "]" + } + ], + "identifier" : { + "interfaceLanguage" : "swift", + "precise" : "__docc_universal_command_reference_$transform-for-static-hosting" + }, + "kind" : { + "displayName" : "Command", + "identifier" : "class" + }, + "names" : { + "subHeading" : [ + { + "kind" : "identifier", + "spelling" : "docc" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "process-archive" + }, + { + "kind" : "text", + "spelling" : " " + }, + { + "kind" : "identifier", + "spelling" : "transform-for-static-hosting" + }, + { + "kind" : "text", + "spelling" : " ..." + } + ], + "title" : "transform-for-static-hosting" + }, + "pathComponents" : [ + "transform-for-static-hosting" + ] + }, { "accessLevel" : "public", "availability" : [ @@ -2001,13 +2731,13 @@ "text" : "" }, { - "text" : "When the ``style`` property is ``Style\/conceptual``, the symbol's name is rendered as \"conceptual\"—same as article names or tutorial names —where applicable. The default style is ``Style\/conceptual``." + "text" : "When the ``style`` property is ``Style\/conceptual``, the symbol's name is rendered as \"conceptual\"---same as article names or tutorial names---where applicable. The default style is ``Style\/conceptual``." }, { "text" : "" }, { - "text" : "When the ``style`` property is ``Style\/symbol``, the symbol's name is rendered as \"symbol\"—same as article names or tutorial names —where applicable. The default style is ``Style\/conceptual``." + "text" : "When the ``style`` property is ``Style\/symbol``, the symbol's name is rendered as \"symbol\"---same as article names or tutorial names---where applicable. The default style is ``Style\/conceptual``." }, { "text" : "" @@ -4094,7 +4824,22 @@ "text" : "" }, { - "text" : "If the page has moved more than once you can add multiple `Redirected` directives, each specifying one previous URL." + "text" : "If the page has moved more than once you can add multiple `Redirected` directives, each specifying one previous URL. For example:" + }, + { + "text" : "" + }, + { + "text" : "```md" + }, + { + "text" : "@Redirected(from: \"old\/path\/to\/this\/page\")" + }, + { + "text" : "@Redirected(from: \"another\/old\/path\/to\/this\/page\")" + }, + { + "text" : "```" }, { "text" : "" @@ -4121,10 +4866,19 @@ "text" : "" }, { - "text" : "To find each page's `Redirected` values, pass the `--emit-digest` flag to DocC and read the \"linkable-entities.json\" file that this makes DocC write to the output directory. " + "text" : "To find each page’s Redirected values, pass the `--emit-digest` flag to DocC." + }, + { + "text" : "This flag configures DocC to write additional metadata files to the output directory." + }, + { + "text" : "One of these files, `linkable-entities.json`, contains summarized information about all pages and on-page landmarks that you can link to from outside the DocC documentation." + }, + { + "text" : "Each of these \"entities\" has a `\"path\"`---which represents the current relative path of that page---and an optional list of `\"redirects\"`---which represent all the `Redirected` values for page as they were authored in the markup." }, { - "text" : "Each \"entity\" in that file has a \"path\"---which represents the current relative path of that page---and an optional list of \"redirects\"---which represent all the `Redirected` values for page as they were authored in the markup. You can write either relative redirect values or absolute redirect values depending on what information you need to set HTTP \"301 Moved Permanently\" redirects on your web server." + "text" : "You can write either relative redirect values or absolute redirect values in the markup depending on what information you need when setting up HTTP \"301 Moved Permanently\" redirects on your web server." }, { "text" : "- Parameters:" diff --git a/Sources/docc/DocCDocumentation.docc/commands.md b/Sources/docc/DocCDocumentation.docc/commands.md new file mode 100644 index 0000000000..4d03bf3164 --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/commands.md @@ -0,0 +1,35 @@ +# Commands + +Run DocC in build scripts or build workflows. + +## Overview + +To build documentation for your Swift package, it is recommended to use a higher level tool like the Swift Package Manager or Xcode. Those higher level tools are responsible for integrating DocC in the larger build workflow and communicating with the Swift and Clang compilers to extract information for your source code and pass that information to DocC. +To learn more about building documentation with the Swift Package Manager, see [the Swift-DocC Plugin documentation](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/). + +If you are building your project using a custom build workflow, you can call the `docc` executable---that's included with the Swift toolchain---yourself from your build scripts. Note that your build scripts are also responsible for communicating with the Swift and Clang compilers to extract information for your source code and pass that information to DocC. + +## Topics + +### Build documentation + +- ``convert`` + +### Locally preview documentation + +- ``preview`` + +### Process documentation archives + +- ``index`` +- ``transform-for-static-hosting`` + +### Process documentation catalogs + +- ``emit-generated-curation`` + +### Get started + +- ``init`` + + diff --git a/Sources/generate-symbol-graph/CommandUsageParser.swift b/Sources/generate-symbol-graph/CommandUsageParser.swift new file mode 100644 index 0000000000..466d82cf93 --- /dev/null +++ b/Sources/generate-symbol-graph/CommandUsageParser.swift @@ -0,0 +1,86 @@ +/* + This source file is part of the Swift.org open source project + + Copyright (c) 2024 Apple Inc. and the Swift project authors + Licensed under Apache License v2.0 with Runtime Library Exception + + See https://swift.org/LICENSE.txt for license information + See https://swift.org/CONTRIBUTORS.txt for Swift project authors +*/ + +struct CommandUsageToken: Equatable { + var text: String + var kind: Kind + enum Kind: Equatable { + case command, text, flag, value + } +} + +struct CommandUsageScanner { + private var remaining: Substring + + init(_ original: Substring) { + remaining = original + } + + func peek() -> Character? { + remaining.first + } + + mutating func take(_ count: Int = 1) -> Substring { + defer { remaining = remaining.dropFirst(count) } + return remaining.prefix(count) + } + + mutating func takeAll() -> Substring { + defer { remaining.removeAll() } + return remaining + } + + mutating func scan(until predicate: (Character) -> Bool) -> Substring? { + guard let index = remaining.firstIndex(where: predicate) else { + return nil + } + defer { remaining = remaining[index...] } + return remaining[.. Bool) -> Substring? { + return scan(until: { !predicate($0) }) + } + + var isAtEnd: Bool { + remaining.isEmpty + } + + func hasPrefix(_ prefix: String) -> Bool { + remaining.hasPrefix(prefix) + } + + // MARK: Parsing argument types by scanning + + mutating func scanTokens() -> [CommandUsageToken] { + var arguments = [CommandUsageToken]() + repeat { + switch peek() { + case "<": + let valueName = scan(until: { $0 == ">" }).map { $0 + take() } ?? takeAll() + arguments.append(.init(text: String(valueName), kind: .value)) + + case "-": + let flagName = scan(until: { $0.isWhitespace }) ?? takeAll() + arguments.append(.init(text: String(flagName), kind: .flag)) + + case " ", "]": + let text = scan(while: { $0 == " " || $0 == "]" || $0 == "[" || $0 == "\\" || $0 == "\n" }) ?? takeAll() + arguments.append(.init(text: String(text), kind: .text)) + + default: + let valueName = scan(until: { $0 == " " }) ?? takeAll() + arguments.append(.init(text: String(valueName), kind: .command)) + } + } while !isAtEnd + + return arguments + } +} diff --git a/Sources/generate-symbol-graph/main.swift b/Sources/generate-symbol-graph/main.swift index 380eb34fe3..21d1c0bc64 100644 --- a/Sources/generate-symbol-graph/main.swift +++ b/Sources/generate-symbol-graph/main.swift @@ -581,7 +581,7 @@ func declarationFragments( return fragments } -let symbols: [SymbolGraph.Symbol] = supportedDirectives.map { directive in +var symbols: [SymbolGraph.Symbol] = supportedDirectives.map { directive in let fragments = declarationFragments( for: directive.name, primaryReference: true, @@ -637,6 +637,136 @@ let symbols: [SymbolGraph.Symbol] = supportedDirectives.map { directive in ) } +struct DocumentedCommand { + var name: String + var introduced: String + var deprecated: String? + var usage: String +} + +let documentedCommands = [ + DocumentedCommand( + name: "convert", + introduced: "5.5", + usage: """ + docc convert \\ + [] + [--additional-symbol-graph-dir ] \\ + [--output-dir ] \\ + [] \\ + [] \\ + [] \\ + [] \\ + [] \\ + [] \\ + [] + """ + ), + + DocumentedCommand( + name: "preview", + introduced: "5.5", + usage: """ + docc preview \\ + [--port ] \\ + [] + """ + ), + + DocumentedCommand( + name: "index", + introduced: "5.5", + usage: """ + docc process-archive index \\ + [] \\ + --bundle-identifier \\ + [--verbose] + """ + ), + + DocumentedCommand( + name: "transform-for-static-hosting", + introduced: "5.6", + usage: """ + docc process-archive transform-for-static-hosting \\ + [] \\ + [--output-path ] \\ + [--hosting-base-path ] + """ + ), + + DocumentedCommand( + name: "emit-generated-curation", + introduced: "5.11", + usage: """ + docc process-catalog emit-generated-curation \\ + [] \\ + [--additional-symbol-graph-dir ] \\ + [--output-path ] \\ + [--from-symbol ] \\ + [--depth ] + """ + ), + + DocumentedCommand( + name: "init", + introduced: "5.11", + usage: """ + docc init \\ + --name \\ + --output-dir \\ + --template + """ + ), +] + +symbols += documentedCommands.map { command in + var scanner = CommandUsageScanner(command.usage[...]) + let declarationFragments: [SymbolGraph.Symbol.DeclarationFragments.Fragment] = scanner.scanTokens().map { + switch $0.kind { + case .command: + return .init(kind: .identifier, spelling: $0.text, preciseIdentifier: nil) + case .text: + return .init(kind: .text, spelling: $0.text, preciseIdentifier: nil) + case .flag: + return .init(kind: .externalParameter, spelling: $0.text, preciseIdentifier: nil) + case .value: + return .init(kind: .typeIdentifier, spelling: $0.text, preciseIdentifier: nil) + } + } + + let subHeading = declarationFragments + .filter { $0.kind == .identifier } + .flatMap { [$0, .init(kind: .text, spelling: " ", preciseIdentifier: nil)] } + .dropLast() + [.init(kind: .text, spelling: " ...", preciseIdentifier: nil)] + + return SymbolGraph.Symbol( + identifier: SymbolGraph.Symbol.Identifier(precise: "__docc_universal_command_reference_$\(command.name)", interfaceLanguage: "swift"), + names: SymbolGraph.Symbol.Names(title: command.name, navigator: nil, subHeading: Array(subHeading), prose: nil), + pathComponents: [command.name], + docComment: nil, + accessLevel: .public, + kind: SymbolGraph.Symbol.Kind(parsedIdentifier: .class, displayName: "Command"), + mixins: [ + SymbolGraph.Symbol.DeclarationFragments.mixinKey: SymbolGraph.Symbol.DeclarationFragments(declarationFragments: declarationFragments), + + SymbolGraph.Symbol.Availability.mixinKey: SymbolGraph.Symbol.Availability(availability: [ + .init( + domain: .init(rawValue: "Swift-DocC"), + introducedVersion: .init(string: command.introduced), + deprecatedVersion: command.deprecated.flatMap { .init(string: $0) }, + obsoletedVersion: nil, + message: nil, + renamed: nil, + isUnconditionallyDeprecated: false, + isUnconditionallyUnavailable: false, + willEventuallyBeDeprecated: false + ) + ]) + ] + ) +} + // Emits SGFs for the different directives we support. let symbolGraph = SymbolGraph( metadata: SymbolGraph.Metadata(