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

Conversation

d-ronnqvist
Copy link
Contributor

Bug/issue #, if applicable: rdar://119262681

Summary

This publishes a refinement of the command line help text for the docc executable's commands in the hosted documentation. For example:

Screenshot 2024-02-20 at 14 48 16 Screenshot 2024-02-20 at 14 45 35

Dependencies

None

Testing

Run docc preview Sources/docc/DocCDocumentation.docc and inspect the documented commands.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

  • [ ] Added tests
  • Ran the ./bin/test script and it succeeded
  • Updated documentation if necessary

Copy link
Contributor

@patshaughnessy patshaughnessy left a comment

Choose a reason for hiding this comment

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

I'd just fix the one typo, but I left a few other optional suggestions also.

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

Choose a reason for hiding this comment

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

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.
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?

### 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.

@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.

@@ -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.


let subHeading = declarationFragments
.filter { $0.kind == .identifier }
.flatMap { [$0, .init(kind: .text, spelling: " ", preciseIdentifier: nil)] }
Copy link
Contributor

Choose a reason for hiding this comment

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

Could you use joined(separator:) here instead? Seems like the perfect use case for it.

Copy link
Contributor

@mayaepps mayaepps left a comment

Choose a reason for hiding this comment

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

Thanks for writing these docs! I think it will be very helpful, I just had a few questions.


## 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?


- ``emit-generated-curation``

### Get started
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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.
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 😄

### 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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants