Document the supported arguments, flags, and options for DocC's CLI #837
Conversation
d-ronnqvist
requested review from
patshaughnessy,
QuietMisdreavus,
franklinsch,
daniel-grumberg,
sofiaromorales and
mayaepps
d-ronnqvist
unassigned patshaughnessy, QuietMisdreavus, franklinsch, daniel-grumberg, sofiaromorales and mayaepps
| 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. |
There was a problem hiding this comment.
It might be a good idea to add a follow on paragraph here mentioning that using docc to generate markdown/article-only documentation is a good use case for the command line, because there's no need to communicate with Swift or Clang.
| 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.
Should we mention here that DocC automatically detects and uses SG files found inside the catalog?
| ### 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.
Typo
| The base path where your will host your documentation. | |
| The base path where you will host your documentation. |
| @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.
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.
| @@ -0,0 +1,27 @@ | |||
| # ``init`` | |||
|
|
|||
| Create a documentation catalog from a template. | |||
There was a problem hiding this comment.
I'd rewrite this abstract to focus on the result, and not on the template:
| Create a documentation catalog from a template. | |
| Create a new documentation catalog you can use as a starting point for your project. |
|
|
||
| let subHeading = declarationFragments | ||
| .filter { $0.kind == .identifier } | ||
| .flatMap { [$0, .init(kind: .text, spelling: " ", preciseIdentifier: nil)] } |
There was a problem hiding this comment.
Could you use joined(separator:) here instead? Seems like the perfect use case for it.
|
|
||
| ## 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.
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?
|
|
||
| - ``emit-generated-curation`` | ||
|
|
||
| ### Get started |
There was a problem hiding this comment.
Is there a particular order to this list? Just had the thought that "Get Started" -> "Locally preview documentation" -> "Build documentation" (or similar) is closer to the order that I imagine someone new to DocC might use these commands.
There was a problem hiding this comment.
It's the same order that the commands are presented if you run docc --help
| ### 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.
How does using this option affect what convert does?
I also have the same question for the next two options too 😄
| ### Inputs & Outputs | ||
|
|
||
| - term `<catalog-path>`: | ||
| Path to the documentation catalog ('.docc') directory. |
There was a problem hiding this comment.
What is used if no catalog-path is provided?
Bug/issue #, if applicable: rdar://119262681
Summary
This publishes a refinement of the command line help text for the
doccexecutable's commands in the hosted documentation. For example:Dependencies
None
Testing
Run
docc preview Sources/docc/DocCDocumentation.doccand inspect the documented commands.Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
[ ] Added tests./bin/testscript and it succeeded