Skip to content
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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Sources/docc/DocCDocumentation.docc/Assets/command-icon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
175 changes: 175 additions & 0 deletions Sources/docc/DocCDocumentation.docc/Commands/convert.md
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.
Copy link
Contributor

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?


- term `--additional-symbol-graph-dir <additional-symbol-graph-dir>`:
A path to a directory of additional symbol graph files.
Copy link
Contributor

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does using this option affect what convert does?

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo

Suggested change
The base path where your will host your documentation.
The base path where you 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. -->

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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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. -->
32 changes: 32 additions & 0 deletions Sources/docc/DocCDocumentation.docc/Commands/index.md
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add another sentence here explaining that this is equivalent to using docc convert --emit-lmdb-index, and that you would use this when the archive was already created.


## 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. -->
27 changes: 27 additions & 0 deletions Sources/docc/DocCDocumentation.docc/Commands/init.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# ``init``

Create a documentation catalog from a template.
Copy link
Contributor

Choose a reason for hiding this comment

The 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
Create a documentation catalog from a template.
Create a new documentation catalog you can use as a starting point for your project.


@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. -->
23 changes: 23 additions & 0 deletions Sources/docc/DocCDocumentation.docc/Commands/preview.md
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. -->
4 changes: 4 additions & 0 deletions Sources/docc/DocCDocumentation.docc/DocC Documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. -->
Loading