Document the supported arguments, flags, and options for DocC's CLI #837

d-ronnqvist · 2024-02-20T13:52:44Z

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:

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

rdar://119262681

patshaughnessy

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

patshaughnessy · 2024-02-21T16:31:28Z

Sources/docc/DocCDocumentation.docc/commands.md

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


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.

patshaughnessy · 2024-02-21T16:34:40Z

Sources/docc/DocCDocumentation.docc/Commands/convert.md

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


Should we mention here that DocC automatically detects and uses SG files found inside the catalog?

patshaughnessy · 2024-02-21T16:37:51Z

Sources/docc/DocCDocumentation.docc/Commands/convert.md

+### Hosting Options (Swift-DocC 5.6+)
+
+- term `--hosting-base-path <hosting-base-path>`:
+  The base path where your will host your documentation.


Typo

Suggested change

The base path where your will host your documentation.

The base path where you will host your documentation.

patshaughnessy · 2024-02-21T18:08:41Z

Sources/docc/DocCDocumentation.docc/Commands/index.md

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


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.

patshaughnessy · 2024-02-21T18:10:30Z

Sources/docc/DocCDocumentation.docc/Commands/init.md

@@ -0,0 +1,27 @@
+# ``init``
+
+Create a documentation catalog from a template.


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.

patshaughnessy · 2024-02-21T18:18:06Z

Sources/generate-symbol-graph/main.swift

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


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

mayaepps

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

mayaepps · 2024-02-21T22:31:30Z

Sources/docc/DocCDocumentation.docc/Commands/emit-generated-curation.md

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


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?

mayaepps · 2024-02-21T22:52:46Z

Sources/docc/DocCDocumentation.docc/commands.md

+
+- ``emit-generated-curation``
+
+### Get started


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.

It's the same order that the commands are presented if you run docc --help

mayaepps · 2024-02-21T23:22:18Z

Sources/docc/DocCDocumentation.docc/Commands/convert.md

+### Source Repository Options (Swift-DocC 5.8+)
+
+- term `--checkout-path <checkout-path>`:
+  The root path on disk of the repository's checkout.


How does using this option affect what convert does?

I also have the same question for the next two options too 😄

mayaepps · 2024-02-21T23:23:40Z

Sources/docc/DocCDocumentation.docc/Commands/convert.md

+### Inputs & Outputs
+
+- term `<catalog-path>`:
+  Path to the documentation catalog ('.docc') directory.


What is used if no catalog-path is provided?

Document the supported arguments, flags, and options for DocC's CLI

8945459

rdar://119262681

d-ronnqvist added the documentation Improvements or additions to documentation label Feb 20, 2024

d-ronnqvist assigned patshaughnessy, QuietMisdreavus, franklinsch, daniel-grumberg, sofiaromorales and mayaepps Feb 20, 2024

d-ronnqvist requested review from patshaughnessy, QuietMisdreavus, franklinsch, daniel-grumberg, sofiaromorales and mayaepps February 20, 2024 15:28

d-ronnqvist unassigned patshaughnessy, QuietMisdreavus, franklinsch, daniel-grumberg, sofiaromorales and mayaepps Feb 20, 2024

patshaughnessy requested changes Feb 21, 2024

View reviewed changes

mayaepps reviewed Feb 21, 2024

View reviewed changes

Merge branch 'main' into initial-cli-documentation

311817a

d-ronnqvist mentioned this pull request Sep 18, 2024

DNM: Command docs proof-of-concept pitch #1030

Draft

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document the supported arguments, flags, and options for DocC's CLI #837

Document the supported arguments, flags, and options for DocC's CLI #837

d-ronnqvist commented Feb 20, 2024

patshaughnessy left a comment

patshaughnessy Feb 21, 2024

patshaughnessy Feb 21, 2024

patshaughnessy Feb 21, 2024

patshaughnessy Feb 21, 2024

patshaughnessy Feb 21, 2024

patshaughnessy Feb 21, 2024

mayaepps left a comment •

edited

Loading

mayaepps Feb 21, 2024

mayaepps Feb 21, 2024

d-ronnqvist Feb 23, 2024

mayaepps Feb 21, 2024

mayaepps Feb 21, 2024

	The base path where your will host your documentation.
	The base path where you will host your documentation.

		@@ -0,0 +1,27 @@
		# ``init``

		Create a documentation catalog from a template.

	Create a documentation catalog from a template.
	Create a new documentation catalog you can use as a starting point for your project.


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

Document the supported arguments, flags, and options for DocC's CLI #837

Are you sure you want to change the base?

Document the supported arguments, flags, and options for DocC's CLI #837

Conversation

d-ronnqvist commented Feb 20, 2024

Summary

Dependencies

Testing

Checklist

patshaughnessy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mayaepps left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mayaepps left a comment •

edited

Loading