Document the supported arguments, flags, and options for DocC's CLI

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 `<catalog-path>`:
+  Path to the documentation catalog ('.docc') directory.
+
+- term `--additional-symbol-graph-dir <additional-symbol-graph-dir>`:
+  A path to a directory of additional symbol graph files.
+
+- term `-o, --output-path, --output-dir <output-path>`:
+  The location where the documentation compiler writes the built documentation.
+
+### Availability Options
+
+- term `--platform <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 <checkout-path>`:
+  The root path on disk of the repository's checkout.
+
+- term `--source-service <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 <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 <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 <diagnostics-file>` **(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 <diagnostic-filter>`:
+  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 <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  <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 <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 <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 <symbol-kind>`:
+  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 <symbol-kind>`:
+  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 <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.
+
+<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+

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 `<catalog-path>` and `--additional-symbol-graph-dir <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 <symbol-link>` to only write documentation extension files for that symbol and its descendants. This can be combined with `--depth <limit>` 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 <doc:adding-structure-to-your-documentation-pages>.
+
+## Arguments, Flags, and Options
+
+### Inputs & Outputs
+
+- term `<catalog-path>`:          
+  Path to the documentation catalog ('.docc') directory.
+
+- term `--additional-symbol-graph-dir <symbol-graph-dir>`:
+  Path to a directory of additional symbol graph files.
+
+- term `--output-path <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 <symbol-link>`:
+  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 <limit>`:
+  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.
+
+<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

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 `<source-archive-path>`:
+  Path to the documentation archive ('.doccarchive') directory to build an LMDB index for.
+
+### Other Options:
+
+- term `--bundle-identifier <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. 
+
+<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

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 <name>` **(required)**:           
+  The base name for the created documentation catalog ('.docc') directory.
+
+- term `-o, --output-dir <output-dir>` **(required)**:
+  The location where the documentation catalog will be written.
+
+- term `--template <template-name>` **(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.
+
+<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

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 <port-number>`:
+  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.
+
+<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

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 `<source-archive-path>`:
+  Path to the documentation archive ('.doccarchive') directory that should be processed.
+
+- term `--output-path <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 <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.
+
+  <!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

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
+
+- <doc:commands>
+
 <!-- Copyright (c) 2021-2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->