From 8e3f00a6769ecd36e68f5745b47b8f84fc6b1ae9 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 4 Jul 2026 21:52:12 -0500 Subject: [PATCH 1/2] docs(fix): clean cross references why: Remove broken and duplicate documentation targets so Sphinx builds cleanly and first mentions resolve to useful destinations. what: - Qualify the rendered logging.Logger API reference - Avoid duplicate argparse section labels in CLI docs - Link first mentions and normalize shell command examples --- docs/cli/completion.md | 24 +++++++++++++----------- docs/cli/index.md | 1 + docs/project/code-style.md | 4 ++-- docs/project/contributing.md | 2 +- docs/project/index.md | 2 +- docs/quickstart.md | 15 ++++++++++----- src/cihai_cli/cli.py | 2 +- 7 files changed, 29 insertions(+), 21 deletions(-) diff --git a/docs/cli/completion.md b/docs/cli/completion.md index 08a82ab..3467877 100644 --- a/docs/cli/completion.md +++ b/docs/cli/completion.md @@ -6,25 +6,27 @@ # Completions +Shell completion lets your shell suggest `cihai` commands and options as you type. + ## cihai-cli 0.15+ (experimental) ```{note} See the [shtab library's documentation on shell completion](https://docs.iterative.ai/shtab/use/#cli-usage) for the most up to date way of connecting completion for cihai-cli. ``` -Provisional support for completions in cihai-cli 0.15+ are powered by [shtab](https://docs.iterative.ai/shtab/). This must be **installed separately**, as it's **not currently bundled with cihai-cli**. +Provisional support for completions in cihai-cli 0.15+ is powered by [shtab](https://docs.iterative.ai/shtab/). This must be **installed separately**, as it's **not currently bundled with cihai-cli**. ```console $ pip install shtab --user ``` -Or manage it inside an existing project with uv: +Or manage it inside an existing project with [uv]: ```console $ uv add --dev shtab ``` -Install `shtab` as a user-wide tool with uv: +Install `shtab` as a user-wide tool with [uv]: ```console $ uv tool install shtab @@ -36,6 +38,8 @@ Run it on-demand without installing: $ uvx shtab ``` +Each shell command below points `shtab` at {func}`cihai_cli.cli.create_parser`, the parser factory used by cihai-cli. + :::{tab} bash ```console @@ -75,10 +79,8 @@ cihai-cli 0.2 to 0.14 use [click](https://click.palletsprojects.com)'s completio _~/.bashrc_: -```bash - -eval "$(_CIHAI_COMPLETE=bash_source cihai)" - +```console +$ eval "$(_CIHAI_COMPLETE=bash_source cihai)" ``` ::: @@ -87,10 +89,10 @@ eval "$(_CIHAI_COMPLETE=bash_source cihai)" _~/.zshrc_: -```zsh - -eval "$(_CIHAI_COMPLETE=zsh_source cihai)" - +```console +$ eval "$(_CIHAI_COMPLETE=zsh_source cihai)" ``` ::: + +[uv]: https://docs.astral.sh/uv/ diff --git a/docs/cli/index.md b/docs/cli/index.md index 04433fb..1729225 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -54,6 +54,7 @@ completion :func: create_parser :prog: cihai :nosubcommands: + :no-description: subparser_name : @replace See :ref:`cli-info`, :ref:`cli-reverse` diff --git a/docs/project/code-style.md b/docs/project/code-style.md index 967bf0c..0145617 100644 --- a/docs/project/code-style.md +++ b/docs/project/code-style.md @@ -2,7 +2,7 @@ ## Formatting -cihai-cli uses [ruff](https://github.com/astral-sh/ruff) for both linting and formatting. +cihai-cli uses [Ruff](https://github.com/astral-sh/ruff) for both linting and formatting. ```console $ uv run ruff format . @@ -22,7 +22,7 @@ $ uv run mypy ## Docstrings -All public functions and methods use NumPy-style docstrings. +All public functions and methods use [NumPy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html). ## Imports diff --git a/docs/project/contributing.md b/docs/project/contributing.md index 00af9b6..cd22f41 100644 --- a/docs/project/contributing.md +++ b/docs/project/contributing.md @@ -1,6 +1,6 @@ # Contributing -cihai-cli follows the cihai project's contributing guidelines. +cihai-cli follows the [cihai project](https://cihai.git-pull.com/)'s contributing guidelines. See the [cihai contributing guide](https://cihai.git-pull.com/contributing/) for development setup, running tests, and submitting pull requests. diff --git a/docs/project/index.md b/docs/project/index.md index a333d15..3cb673a 100644 --- a/docs/project/index.md +++ b/docs/project/index.md @@ -16,7 +16,7 @@ How to get involved and submit changes. :::{grid-item-card} Code Style :link: code-style :link-type: doc -Ruff, mypy, NumPy docstrings, import conventions. +[Ruff](https://github.com/astral-sh/ruff), [mypy](https://mypy-lang.org/), [NumPy](https://numpydoc.readthedocs.io/en/latest/format.html) docstrings, import conventions. ::: :::{grid-item-card} Releasing diff --git a/docs/quickstart.md b/docs/quickstart.md index c1ab947..739a61e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,6 +1,6 @@ -(usage)= +(quickstart)= -# Usage +# Quickstart cihai is designed to work out-of-the-box without configuration. @@ -10,13 +10,13 @@ cihai is designed to work out-of-the-box without configuration. $ pip install --user cihai-cli ``` -Or manage it inside an existing project with uv: +Or manage it inside an existing project with [uv]: ```console $ uv add cihai-cli ``` -Install the CLI as a user-wide tool with uv: +Install the CLI as a user-wide tool with [uv]: ```console $ uv tool install cihai-cli @@ -44,7 +44,12 @@ the 4th beta release of `1.10.0` before general availability. ```console $ pipx install --suffix=@next 'cihai-cli' --pip-args '\--pre' --force - // Usage: cihai@next info 好 + ``` + + Run that prerelease command as `cihai@next`: + + ```console + $ cihai@next info 好 ``` - [uv tool install][uv-tools]\: diff --git a/src/cihai_cli/cli.py b/src/cihai_cli/cli.py index bbe40eb..38760bd 100644 --- a/src/cihai_cli/cli.py +++ b/src/cihai_cli/cli.py @@ -293,7 +293,7 @@ def setup_logger( Parameters ---------- - logger : :py:class:`Logger` + logger : :class:`logging.Logger` Instance of logger, if one set up. """ if not logger: From 45c3ae59830bfb7c41c6c3c7214d1a6f28a1c875 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 4 Jul 2026 22:04:00 -0500 Subject: [PATCH 2/2] docs(changelog): add docs cleanup entry why: Give the documentation cleanup a user-facing unreleased changelog item and keep the rendered migration page linked to the changelog. what: - Add a high-level documentation entry for clearer links and copyable examples - Point the migration notes at the existing changelog page label --- CHANGES | 9 +++++++++ MIGRATION | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 91c0a40..69c115c 100644 --- a/CHANGES +++ b/CHANGES @@ -39,6 +39,15 @@ $ uvx --from 'cihai-cli' --prerelease allow cihai _Notes on the upcoming release will go here._ +### Documentation + +#### Clearer documentation links and examples (#354) + +Documentation pages now link readers from the first mention of key tools, API +entry points, and command pages to the right reference. The quickstart and +completion pages also keep shell examples copyable by moving explanatory text +into prose, so readers can follow setup steps without editing copied commands. + ## cihai-cli 0.34.0 (2026-06-28) cihai-cli 0.34.0 tracks the latest cihai and unihan-etl releases. The `cihai` diff --git a/MIGRATION b/MIGRATION index 109331a..84d8727 100644 --- a/MIGRATION +++ b/MIGRATION @@ -1,6 +1,6 @@ # Migration notes -Migration and deprecation notes for cihai-cli are here, see {ref}`changelog` as +Migration and deprecation notes for cihai-cli are here, see {ref}`history` as well. ```{admonition} Welcome on board! 👋