docs(api,cli) Link API refs and clean CLI docs (#558)

tony · web-flow · commit c1f3905b325b · 2026-07-04T13:52:53.000-05:00
API reference pages now keep module names out of headings so their
first prose mentions can carry Sphinx roles. The PrivatePath intro now
links to its class reference.

The CLI reference no longer renders aggregate parser examples that
duplicate per-command anchors, so the docs build no longer reports
duplicate-label warnings. Legacy shell completion snippets now show
exact startup-file lines without extra blank space.

Verification:
- rm -rf docs/_build; uv run ruff check . --fix --show-fixes; uv run ruff format .; uv run mypy .; uv run py.test --reruns 0 -vvv; just build-docs;
diff --git a/docs/api/config.md b/docs/api/config.md
@@ -1,4 +1,4 @@
-# Config - `vcspull.config`
+# Config
 
 {mod}`vcspull.config` finds, loads, and filters vcspull configuration from
 Python — the same functions the CLI uses to locate configuration files,
diff --git a/docs/api/exc.md b/docs/api/exc.md
@@ -1,4 +1,4 @@
-# Exceptions - `vcspull.exc`
+# Exceptions
 
 When configuration loading or a worktree operation fails, vcspull raises an
 exception from {mod}`vcspull.exc`. Catch
diff --git a/docs/api/log.md b/docs/api/log.md
@@ -1,4 +1,4 @@
-# Logging - `vcspull.log`
+# Logging
 
 {mod}`vcspull.log` holds the logging setup for the vcspull CLI — the
 formatters and colorized output behind its console messages.
diff --git a/docs/api/types.md b/docs/api/types.md
@@ -1,4 +1,4 @@
-# Typings - `vcspull.types`
+# Typings
 
 {mod}`vcspull.types` defines the typed dictionaries and aliases that
 describe configuration data on its way from file to sync — the annotations
diff --git a/docs/api/util.md b/docs/api/util.md
@@ -1,4 +1,4 @@
-# Utilities - `vcspull.util`
+# Utilities
 
 {mod}`vcspull.util` collects the small helpers shared across vcspull's
 modules — configuration-directory lookup and recursive dictionary merging.
diff --git a/docs/api/validator.md b/docs/api/validator.md
@@ -1,4 +1,4 @@
-# Validation - `vcspull.validator`
+# Validation
 
 {mod}`vcspull.validator` checks that a parsed configuration has the shape
 vcspull expects — workspace roots mapping to repository entries — before the
diff --git a/docs/cli/completion.md b/docs/cli/completion.md
@@ -86,9 +86,7 @@ vcspull 0.9 to 1.14 use [click](https://click.palletsprojects.com)'s completion:
 _~/.bashrc_:
 
 ```bash
-
 eval "$(_VCSPULL_COMPLETE=bash_source vcspull)"
-
 ```
 
 :::
@@ -98,9 +96,7 @@ eval "$(_VCSPULL_COMPLETE=bash_source vcspull)"
 _~/.zshrc_:
 
 ```zsh
-
 eval "$(_VCSPULL_COMPLETE=zsh_source vcspull)"
-
 ```
 
 :::
diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -110,6 +110,7 @@ completion
     :func: create_parser
     :prog: vcspull
     :nosubcommands:
+    :no-description:
 
     subparser_name : @replace
         See :ref:`cli-sync`, :ref:`cli-add`, :ref:`cli-import`, :ref:`cli-discover`, :ref:`cli-list`, :ref:`cli-search`, :ref:`cli-status`, :ref:`cli-worktree`, :ref:`cli-fmt`, :ref:`cli-migrate`
diff --git a/docs/internals/api/cli/add.md b/docs/internals/api/cli/add.md
@@ -1,4 +1,4 @@
-# vcspull add - `vcspull.cli.add`
+# Add command internals
 
 {mod}`vcspull.cli.add` is the implementation behind
 {ref}`vcspull add <cli-add>` — it resolves a checkout on disk into a
diff --git a/docs/internals/api/cli/discover.md b/docs/internals/api/cli/discover.md
@@ -1,4 +1,4 @@
-# vcspull discover - `vcspull.cli.discover`
+# Discover command internals
 
 {mod}`vcspull.cli.discover` is the implementation behind
 {ref}`vcspull discover <cli-discover>` — it scans a directory tree for
diff --git a/docs/internals/api/cli/fmt.md b/docs/internals/api/cli/fmt.md
@@ -1,4 +1,4 @@
-# vcspull fmt - `vcspull.cli.fmt`
+# Format command internals
 
 {mod}`vcspull.cli.fmt` is the implementation behind
 {ref}`vcspull fmt <cli-fmt>` — it normalizes configuration files to
diff --git a/docs/internals/api/cli/import.md b/docs/internals/api/cli/import.md
@@ -1,4 +1,4 @@
-# vcspull import - `vcspull.cli.import_cmd`
+# Import command internals
 
 {mod}`vcspull.cli.import_cmd` is the implementation behind
 {ref}`vcspull import <cli-import>` — one submodule per forge, sharing
diff --git a/docs/internals/api/cli/index.md b/docs/internals/api/cli/index.md
@@ -20,7 +20,7 @@ fmt
 migrate
 ```
 
-## vcspull CLI - `vcspull.cli`
+## CLI dispatcher internals
 
 {mod}`vcspull.cli` assembles the argument parser and dispatches each
 subcommand to its module — start here to trace how a command line becomes a
diff --git a/docs/internals/api/cli/list.md b/docs/internals/api/cli/list.md
@@ -1,4 +1,4 @@
-# vcspull list - `vcspull.cli.list`
+# List command internals
 
 {mod}`vcspull.cli.list` is the implementation behind
 {ref}`vcspull list <cli-list>` — it prints the repositories your
diff --git a/docs/internals/api/cli/migrate.md b/docs/internals/api/cli/migrate.md
@@ -1,4 +1,4 @@
-# vcspull migrate - `vcspull.cli.migrate`
+# Migrate command internals
 
 {mod}`vcspull.cli.migrate` is the implementation behind
 {ref}`vcspull migrate <cli-migrate>` — it rewrites deprecated configuration
diff --git a/docs/internals/api/cli/search.md b/docs/internals/api/cli/search.md
@@ -1,4 +1,4 @@
-# vcspull search - `vcspull.cli.search`
+# Search command internals
 
 {mod}`vcspull.cli.search` is the implementation behind
 {ref}`vcspull search <cli-search>` — it matches repositories with
diff --git a/docs/internals/api/cli/status.md b/docs/internals/api/cli/status.md
@@ -1,4 +1,4 @@
-# vcspull status - `vcspull.cli.status`
+# Status command internals
 
 {mod}`vcspull.cli.status` is the implementation behind
 {ref}`vcspull status <cli-status>` — it checks configured repositories
diff --git a/docs/internals/api/cli/sync.md b/docs/internals/api/cli/sync.md
@@ -1,4 +1,4 @@
-# vcspull sync - `vcspull.cli.sync`
+# Sync command internals
 
 {mod}`vcspull.cli.sync` is the implementation behind
 {ref}`vcspull sync <cli-sync>` — the planning, filtering, and execution
diff --git a/docs/internals/api/cli/worktree.md b/docs/internals/api/cli/worktree.md
@@ -1,4 +1,4 @@
-# vcspull worktree - `vcspull.cli.worktree`
+# Worktree command internals
 
 {mod}`vcspull.cli.worktree` is the implementation behind
 {ref}`vcspull worktree <cli-worktree>` — it plans and applies declared
diff --git a/docs/internals/api/config_reader.md b/docs/internals/api/config_reader.md
@@ -1,4 +1,4 @@
-# Config reader - `vcspull._internal.config_reader`
+# Config reader
 
 :::{warning}
 Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
diff --git a/docs/internals/api/private_path.md b/docs/internals/api/private_path.md
@@ -1,12 +1,13 @@
-# PrivatePath – `vcspull._internal.private_path`
+# Path redaction internals
 
 :::{warning}
 {class}`~vcspull._internal.private_path.PrivatePath` is an internal helper. Its import path and behavior may change
 without notice. File an issue if you rely on it downstream so we can discuss a
 supported API.
 :::
 
-`PrivatePath` subclasses {class}`pathlib.Path` and normalizes every textual rendering
+{class}`~vcspull._internal.private_path.PrivatePath` subclasses
+{class}`pathlib.Path` and normalizes every textual rendering
 (`str()`/`repr()`) so the current user’s home directory is collapsed to `~`.
 The class behaves exactly like the standard path object for filesystem ops; it
 only alters how the path is displayed. This keeps CLI logs, JSON/NDJSON output,
diff --git a/docs/internals/api/worktree_sync.md b/docs/internals/api/worktree_sync.md
@@ -1,4 +1,4 @@
-# Worktree sync - `vcspull._internal.worktree_sync`
+# Worktree sync
 
 :::{warning}
 Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# Config - `vcspull.config`
	`1`	`+# Config`
`2`	`2`
`3`	`3`	{mod}`vcspull.config` finds, loads, and filters vcspull configuration from
`4`	`4`	`Python — the same functions the CLI uses to locate configuration files,`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# Exceptions - `vcspull.exc`
	`1`	`+# Exceptions`
`2`	`2`
`3`	`3`	`When configuration loading or a worktree operation fails, vcspull raises an`
`4`	`4`	exception from {mod}`vcspull.exc`. Catch
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# Logging - `vcspull.log`
	`1`	`+# Logging`
`2`	`2`
`3`	`3`	{mod}`vcspull.log` holds the logging setup for the vcspull CLI — the
`4`	`4`	`formatters and colorized output behind its console messages.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# Typings - `vcspull.types`
	`1`	`+# Typings`
`2`	`2`
`3`	`3`	{mod}`vcspull.types` defines the typed dictionaries and aliases that
`4`	`4`	`describe configuration data on its way from file to sync — the annotations`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# Utilities - `vcspull.util`
	`1`	`+# Utilities`
`2`	`2`
`3`	`3`	{mod}`vcspull.util` collects the small helpers shared across vcspull's
`4`	`4`	`modules — configuration-directory lookup and recursive dictionary merging.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# Validation - `vcspull.validator`
	`1`	`+# Validation`
`2`	`2`
`3`	`3`	{mod}`vcspull.validator` checks that a parsed configuration has the shape
`4`	`4`	`vcspull expects — workspace roots mapping to repository entries — before the`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# vcspull add - `vcspull.cli.add`
	`1`	`+# Add command internals`
`2`	`2`
`3`	`3`	{mod}`vcspull.cli.add` is the implementation behind
`4`	`4`	{ref}`vcspull add <cli-add>` — it resolves a checkout on disk into a
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# vcspull discover - `vcspull.cli.discover`
	`1`	`+# Discover command internals`
`2`	`2`
`3`	`3`	{mod}`vcspull.cli.discover` is the implementation behind
`4`	`4`	{ref}`vcspull discover <cli-discover>` — it scans a directory tree for