diff --git a/Sources/docc/DocCDocumentation.docc/DocC Documentation.md b/Sources/docc/DocCDocumentation.docc/DocC Documentation.md index 1406753cdc..4e33d506a7 100644 --- a/Sources/docc/DocCDocumentation.docc/DocC Documentation.md +++ b/Sources/docc/DocCDocumentation.docc/DocC Documentation.md @@ -39,6 +39,15 @@ DocC syntax — called _documentation markup_ — is a custom variant of Markdow - +### DocC Commands + +- +- +- +- +- +- + ### Documentation Types - diff --git a/Sources/docc/DocCDocumentation.docc/docc-cli-convert.md b/Sources/docc/DocCDocumentation.docc/docc-cli-convert.md new file mode 100644 index 0000000000..db03af99ed --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/docc-cli-convert.md @@ -0,0 +1,146 @@ +# convert + +Convert documentation markup, assets, and symbol information into a documentation archive. + +## Overview + +`docc convert [] [--additional-symbol-graph-dir ]` +`docc convert [] [--additional-symbol-graph-dir ] [--output-dir ]` +`docc convert [] [--additional-symbol-graph-dir ] [--output-dir ] [] [] [] [] [] [] []` + +### Inputs and Outputs + +- term ``: Path to a '.docc' documentation catalog 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 + +- 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. + Required when using '--source-service-base-url'. Supported values are 'github', 'gitlab', and + 'bitbucket'. +- term `--source-service-base-url `: + The base URL where the source service hosts the project's sources. + Required when using '--source-service'. For example, 'https://github.com/my-org/my-repo/blob/main'. + +### Hosting Options + +- term `--hosting-base-path `: + The base path your documentation website will be hosted at. + 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 `--transform-for-static-hosting/--no-transform-for-static-hosting`: + Produce a DocC archive that supports static hosting environments. (default: + --transform-for-static-hosting) + +### Diagnostic Options + +- term `--analyze`: Include 'note'/'information' level diagnostics in addition to warnings and errors. +- term `--diagnostics-file, --diagnostics-output-path `: + 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`: 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, --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, --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 `: + 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". + +### Experimental Documentation Coverage + +- 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-subcript, instance-variable, module, operator, protocol, structure, + type-alias, type-method, type-property, type-subscript, typedef + +### Experimental Link Resolution Options + +- term `--dependency `: + A path to a documentation archive 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: allow catalog directories without the `.docc` extension. +- term `--enable-experimental-external-link-support`: + 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`: + Collects all the symbols that are overloads of each other onto a new + merged-symbol page. +- term `--enable-experimental-mentioned-in`: + Render a section on symbol documentation which links to articles that mention + that symbol + Validates and filters symbols' parameter and return value documentation based on the symbol's + function signature in each language representation. +- term `--enable-parameters-and-returns-validation/--disable-parameters-and-returns-validation`: + Validate parameter and return value documentation (default: + --enable-parameters-and-returns-validation) + 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. diff --git a/Sources/docc/DocCDocumentation.docc/docc-cli-init.md b/Sources/docc/DocCDocumentation.docc/docc-cli-init.md new file mode 100644 index 0000000000..4d16ff4778 --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/docc-cli-init.md @@ -0,0 +1,25 @@ +# init + +Generate a documentation catalog from the selected template. + +## Overview + +`docc init --name --output-dir --template ` + +### Options + +- term `--name `: Name to use as the catalog directory name +- term `-o, --output-dir `: + The location where the documentation catalog will be written +- term `--template `: + The catalog template to initialize. + +The provided templates are: + +- articleOnly: This template contains the minimal needed for creating article-only reference +documentation not tied to symbols. It includes a catalog with just one markdown file and a +references folder. + +- tutorial: This template contains the necessary structure and directives to get started on +authoring tutorials. + diff --git a/Sources/docc/DocCDocumentation.docc/docc-cli-merge.md b/Sources/docc/DocCDocumentation.docc/docc-cli-merge.md new file mode 100644 index 0000000000..1ee5ad477b --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/docc-cli-merge.md @@ -0,0 +1,18 @@ +# merge + +Merge a list of documentation archives into a combined archive. + +## Overview + +`docc merge ... [--landing-page-catalog ] [--output-path ]` + +### Options + +- term ``: A list of paths to '.doccarchive' documentation archive directories to combine + into a combined archive. +- term `--landing-page-catalog `: + Path to a '.docc' documentation catalog directory with content for the landing + page. +- term `-o, --output-path `: + The location where the documentation compiler writes the combined documentation + archive. diff --git a/Sources/docc/DocCDocumentation.docc/docc-cli-preview.md b/Sources/docc/DocCDocumentation.docc/docc-cli-preview.md new file mode 100644 index 0000000000..d03d9289d6 --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/docc-cli-preview.md @@ -0,0 +1,126 @@ +# preview + +Convert documentation inputs and preview the documentation output. + +## Overview + +`docc preview [] [--port ] [--additional-symbol-graph-dir ` +`docc preview [] [--port ] [--additional-symbol-graph-dir ] [--output-dir ]` +`docc preview [] [--port ] [--additional-symbol-graph-dir ] [--output-dir ] [] [] [] [] [] [] []` + +### Options + +- term `-p, --port `: + Port number to use for the preview web server. (default: 8080) +- term ``: Path to a '.docc' documentation catalog 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. +- 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. +- 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. + Required when using '--source-service-base-url'. Supported values are 'github', 'gitlab', and + 'bitbucket'. +- term `--source-service-base-url `: + The base URL where the source service hosts the project's sources. + Required when using '--source-service'. For example, 'https://github.com/my-org/my-repo/blob/main'. +- term `--hosting-base-path `: + The base path your documentation website will be hosted at. + 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 `--transform-for-static-hosting/--no-transform-for-static-hosting`: + Produce a DocC archive that supports static hosting environments. (default: + `--transform-for-static-hosting`) +- term `--analyze`: Include 'note'/'information' level diagnostics in addition to warnings and errors. +- term `--diagnostics-file, --diagnostics-output-path `: + 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`: Treat warnings as errors +- 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, --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, --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 `: + 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". +- 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-subcript, instance-variable, module, operator, protocol, structure, + type-alias, type-method, type-property, type-subscript, typedef +- term `--dependency `: + A path to a documentation archive to resolve external links against. + Only documentation archives built with '--enable-experimental-external-link-support' are supported + as dependencies. +- 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: allow catalog directories without the `.docc` extension. +- term `--enable-experimental-external-link-support`: + 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`: + Collects all the symbols that are overloads of each other onto a new + merged-symbol page. +- term `--enable-experimental-mentioned-in`: + Render a section on symbol documentation which links to articles that mention + that symbol + Validates and filters symbols' parameter and return value documentation based on the symbol's + function signature in each language representation. +- term `--enable-parameters-and-returns-validation/--disable-parameters-and-returns-validation`: + Validate parameter and return value documentation (default: + `--enable-parameters-and-returns-validation`) + 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. diff --git a/Sources/docc/DocCDocumentation.docc/docc-cli-process-archive.md b/Sources/docc/DocCDocumentation.docc/docc-cli-process-archive.md new file mode 100644 index 0000000000..84edb708cb --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/docc-cli-process-archive.md @@ -0,0 +1,15 @@ +# process-archive + +Perform operations on documentation archives ('.doccarchive' directories). + +## Overview + +`docc process-archive ` + +### Subcommands + +- term `transform-for-static-hosting`: + - `docc process-archive transform-for-static-hosting [] [--output-path ] [--hosting-base-path ]` + +- term `index`: + - `docc process-archive index [] --bundle-identifier [--verbose]` diff --git a/Sources/docc/DocCDocumentation.docc/docc-cli-process-catalog.md b/Sources/docc/DocCDocumentation.docc/docc-cli-process-catalog.md new file mode 100644 index 0000000000..c28e532dc9 --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/docc-cli-process-catalog.md @@ -0,0 +1,14 @@ +# process-catalog + +Perform operations on documentation catalogs ('.docc' directories). + +## Overview + +`docc process-catalog ` + +### Subcommands + +- term `emit-generated-curation` : Write documentation extension files with markdown representations of DocC's +automatic curation. + - `docc process-catalog emit-generated-curation [] [--additional-symbol-graph-dir ] [--output-path ] [--from-symbol ] [--depth ]` +