-
Notifications
You must be signed in to change notification settings - Fork 126
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document the supported arguments, flags, and options for DocC's CLI #837
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -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. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should we mention here that DocC automatically detects and uses SG files found inside the catalog? |
||||||
|
||||||
- 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. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. How does using this option affect what I also have the same question for the next two options too 😄 |
||||||
|
||||||
- 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. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Typo
Suggested change
|
||||||
|
||||||
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. --> | ||||||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I wonder if it would be useful to mention first what the intended use case is for this command before going into how to use it? |
||
|
||
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. --> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe add another sentence here explaining that this is equivalent to using |
||
|
||
## 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. --> |
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,27 @@ | ||||||
# ``init`` | ||||||
|
||||||
Create a documentation catalog from a template. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'd rewrite this abstract to focus on the result, and not on the template:
Suggested change
|
||||||
|
||||||
@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. --> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. --> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. --> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is used if no
catalog-path
is provided?