docs(style): align docs references

why: docs guidance requires useful first-mention links and
one-command console examples so readers can navigate reference docs
without parsing inline shell prose.

what:
- Link CLI option, API, and external project references
- Split contributor and release shell examples into console blocks
- Keep changelog headings linkable without unlinked first mentions

Author: tony

CHANGES

@@ -42,17 +42,17 @@ g 0.0.10 turns g's documentation into a usable CLI reference and moves the docs
 
 ### What's new
 
-#### `g --version` / `g -V` report g's version (#46)
+#### {argparse:option}`g --version` / {argparse:option}`g -V` report g's version (#46)
 
-`g --version` and `g -V` now print g's installed version instead of forwarding those flags to `git`, `svn`, or `hg`. This gives users a direct way to confirm which wrapper version is on `PATH` while keeping the normal proxy behavior unchanged for VCS commands.
+{argparse:option}`g --version` and {argparse:option}`g -V` now print g's installed version instead of forwarding those flags to `git`, `svn`, or `hg`. This gives users a direct way to confirm which wrapper version is on `PATH` while keeping the normal proxy behavior unchanged for VCS commands.
 
 The implementation preserves the existing {func}`g.run` test hook: in test mode the version path returns cleanly instead of exiting through {mod}`argparse`, so the behavior can be asserted without special subprocess handling.
 
 #### First-party CLI reference page (#46)
 
-The new {doc}`cli/index` page explains g's repository detection flow, shows command equivalence examples, and renders {func}`g.create_parser` through the argparse documentation extension. Argument sections now have stable anchors, so users can link directly to the version flags or pass-through argument reference.
+The new {doc}`cli/index` page explains g's repository detection flow, shows command equivalence examples, and renders {func}`g.create_parser` through the argparse documentation extension. Argument sections now have stable anchors, so users can link directly to the {argparse:option}`version flags <g --version>` or {argparse:positional}`pass-through argument reference <g vcs_args>`.
 
-The CLI docs also clarify the one exception to g's pass-through model: `--version` and `-V` are handled by g itself, while the remaining arguments are sent to the detected VCS command.
+The CLI docs also clarify the one exception to g's pass-through model: {argparse:option}`--version <g --version>` and {argparse:option}`-V <g -V>` are handled by g itself, while the remaining arguments are sent to the detected VCS command.
 
 #### Documentation frontend refresh (#50, #51)
 
@@ -80,7 +80,7 @@ of lines of local documentation plumbing.
 ### Fixes
 
 - The CLI documentation cards now use reference links instead of URL-fragment options, avoiding MyST directive parsing warnings in grid cards (#54).
-- The manual CLI "Usage" section was renamed to "Usage examples" so it no longer collides with the argparse-generated `usage` anchor (#54).
+- The manual CLI "Usage" section was renamed to "Usage examples" so it no longer collides with the argparse-generated {ref}`usage` anchor (#54).
 - Light and dark mode CSS for argparse metadata and header links now handles Furo's automatic theme mode correctly (#46).
 
 ### Documentation
@@ -100,13 +100,13 @@ matching reference material.
 
 ## g 0.0.9 (2026-01-24)
 
-g 0.0.9 hardens release and documentation publishing. The project no longer relies on long-lived PyPI or AWS secrets for the main publishing paths, and the release job now participates in PyPI's trusted-publishing and attestation flow.
+g 0.0.9 hardens release and documentation publishing. The project no longer relies on long-lived [PyPI](https://pypi.org/) or [AWS](https://aws.amazon.com/) secrets for the main publishing paths, and the release job now participates in PyPI's trusted-publishing and attestation flow.
 
 ### What's new
 
-#### PyPI Trusted Publisher release flow (#43)
+#### Trusted Publisher release flow (#43)
 
-Package publishing moved from stored API credentials to PyPI Trusted Publisher via [GitHub Actions](https://docs.github.com/actions) OIDC. The release workflow requests `id-token` and attestation permissions, publishes without embedding a PyPI token in repository secrets, and fixes the deprecated `skip_existing` input name along the way.
+Package publishing moved from stored API credentials to [PyPI Trusted Publisher](https://docs.pypi.org/trusted-publishers/) via [GitHub Actions](https://docs.github.com/actions) [OIDC](https://openid.net/developers/how-connect-works/). The release workflow requests `id-token` and attestation permissions, publishes without embedding a PyPI token in repository secrets, and fixes the deprecated `skip_existing` input name along the way.
 
 #### OIDC-backed documentation deployment
 
@@ -119,7 +119,7 @@ Documentation deployment moved to AWS OIDC authentication and the [AWS CLI](http
 
 ## g 0.0.8 (2025-11-01)
 
-g 0.0.8 updates the supported Python window for current runtimes. Python 3.9 support is removed after end of life, and Python 3.14 is added to the classifiers, test matrix, and docs build path.
+g 0.0.8 updates the supported [Python](https://www.python.org/) window for current runtimes. Python 3.9 support is removed after end of life, and Python 3.14 is added to the classifiers, test matrix, and docs build path.
 
 ### Breaking changes
 
@@ -213,15 +213,15 @@ g 0.0.3 tightens the development harness around the small CLI wrapper. The relea
 
 ### Documentation
 
-#### Docstrings and pydocstyle enforcement (#18)
+#### Docstring style enforcement (#18)
 
-Ruff now enforces pydocstyle with the NumPy convention, and the public modules, functions, tests, and docs configuration were updated with compliant docstrings. This makes the API documentation and doctest surface less dependent on undocumented behavior.
+Ruff now enforces [pydocstyle](https://www.pydocstyle.org/) with the [NumPy](https://numpydoc.readthedocs.io/en/latest/format.html) convention, and the public modules, functions, tests, and docs configuration were updated with compliant docstrings. This makes the API documentation and doctest surface less dependent on undocumented behavior.
 
 ### Development
 
-#### Pytest and Poetry configuration cleanup (#14)
+#### Test and packaging configuration cleanup (#14)
 
-Pytest configuration moved into `pyproject.toml`, and Poetry development dependencies moved from extras into proper dependency groups. That layout matches Poetry's current model and keeps test configuration next to the rest of the project metadata.
+[Pytest](https://docs.pytest.org/) configuration moved into `pyproject.toml`, and Poetry development dependencies moved from extras into proper dependency groups. That layout matches Poetry's current model and keeps test configuration next to the rest of the project metadata.
 
 #### Ruff replaces the older formatting and lint stack (#11, #17)
 
@@ -251,7 +251,7 @@ The import package moved under `src/g`, with CI and docs paths updated to match.
 
 #### Early lint rule coverage (#4, #5)
 
-The development stack added flake8-bugbear and flake8-comprehensions, giving the small codebase better checks for common Python mistakes and simplification opportunities.
+The development stack added [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear) and [flake8-comprehensions](https://github.com/adamchainz/flake8-comprehensions), giving the small codebase better checks for common Python mistakes and simplification opportunities.
 
 ## g 0.0.1 (2022-08-17)
 
@@ -281,7 +281,7 @@ The first docs site used Sphinx, the Furo theme, and `sphinx-autobuild` for loca
 
 ### Development
 
-Initial CI, Codecov, S3, and [CloudFront](https://aws.amazon.com/cloudfront/) deployment plumbing landed with the package scaffold.
+Initial CI, [Codecov](https://about.codecov.io/), [S3](https://aws.amazon.com/s3/), and [CloudFront](https://aws.amazon.com/cloudfront/) deployment plumbing landed with the package scaffold.
 
 <!---
 .. vim: set filetype=markdown:

docs/api.md

@@ -4,7 +4,8 @@ Most users do not need this page. Start with {doc}`quickstart` or
 {doc}`cli/index` if you only want the command-line wrapper.
 
 ```{note}
-These APIs are private and can break between versions. If you want to use them directly, file an issue on the tracker.
+These APIs are private and can break between versions. If you want to use them
+directly, file an issue on the [tracker].
 ```
 
 ```{eval-rst}
@@ -13,3 +14,5 @@ These APIs are private and can break between versions. If you want to use them d
    :show-inheritance:
    :undoc-members:
 ```
+
+[tracker]: https://github.com/vcs-python/g/issues

docs/cli/index.md

@@ -30,7 +30,8 @@ When you run `g`, it:
 2. Invokes the corresponding VCS (`git`, `svn`, or `hg`) with your arguments
 3. Exits after the command completes
 
-**Note:** `--version`/`-V` is handled by g itself rather than passed to the VCS.
+**Note:** {argparse:option}`--version <g --version>`/{argparse:option}`-V <g -V>`
+is handled by g itself rather than passed to the VCS.
 
 ## Usage examples
 

docs/index.md

@@ -46,7 +46,23 @@ See {doc}`quickstart` for all installation methods and first steps.
 $ g status
 ```
 
-Inside a git repo this runs `git status`; inside an svn checkout it runs `svn status`; inside a mercurial repo it runs `hg status`.
+Inside a git repo, that is equivalent to:
+
+```console
+$ git status
+```
+
+Inside an svn checkout:
+
+```console
+$ svn status
+```
+
+Inside a mercurial repo:
+
+```console
+$ hg status
+```
 
 [Git]: https://git-scm.com/
 [Mercurial]: https://www.mercurial-scm.org/

docs/project/contributing.md

@@ -40,8 +40,17 @@ $ make test
 
 ## Automatically run tests on file save
 
-1. `make start` (via [pytest-watcher])
-2. `make watch_test` (requires installing [entr(1)])
+Run tests once, then keep watching with [pytest-watcher]:
+
+```console
+$ make start
+```
+
+Watch through [entr(1)] if you have it installed:
+
+```console
+$ make watch_test
+```
 
 [pytest-watcher]: https://github.com/olzhasar/pytest-watcher
 
@@ -52,22 +61,62 @@ Default preview server: http://localhost:8034
 [sphinx-autobuild] builds the docs, watches for file changes, and launches a
 server.
 
-From home directory: `make start_docs`
-From inside `docs/`: `make start`
+From the project root:
+
+```console
+$ make start_docs
+```
+
+From inside `docs/`:
+
+```console
+$ make start
+```
 
 [sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild
 
 ### Manual documentation
 
-`cd docs/` and `make html` to build. `make serve` to start http server.
+Enter the docs directory:
 
-Helpers:
-`make build_docs`, `make serve_docs`
+```console
+$ cd docs
+```
+
+Build the docs:
 
-Rebuild docs on file change: `make watch_docs` (requires [entr(1)])
+```console
+$ make html
+```
 
-Rebuild docs and run server via one terminal: `make dev_docs` (requires above, and a
-`make(1)` with `-J` support, e.g. GNU Make)
+Start the HTTP server:
+
+```console
+$ make serve
+```
+
+Project-root helpers run the same docs tasks:
+
+```console
+$ make build_docs
+```
+
+```console
+$ make serve_docs
+```
+
+Rebuild docs on file change with [entr(1)]:
+
+```console
+$ make watch_docs
+```
+
+Rebuild docs and run the server through one terminal when your [GNU Make] has
+`-J` support:
+
+```console
+$ make dev_docs
+```
 
 ## Formatting / Linting
 
@@ -200,6 +249,7 @@ See {doc}`/project/releasing` before preparing a release.
 [uv]: https://github.com/astral-sh/uv
 [entr(1)]: http://eradman.com/entrproject/
 [`entr(1)`]: http://eradman.com/entrproject/
+[GNU Make]: https://www.gnu.org/software/make/
 [ruff format]: https://docs.astral.sh/ruff/formatter/
 [ruff]: https://ruff.rs
 [mypy]: http://mypy-lang.org/

docs/project/releasing.md

@@ -3,8 +3,8 @@
 ## Release Process
 
 Use this page when you are preparing a g release. Tags trigger publishing to
-PyPI via OIDC trusted publishing, so create and push them only when you intend
-to publish.
+[PyPI] via [OIDC] trusted publishing, so create and push them only when you
+intend to publish.
 
 1. Update `CHANGES` with the release notes
 
@@ -18,13 +18,22 @@ to publish.
    $ git tag v<version>
    ```
 
-5. Push the branch and tag:
+5. Push the branch:
 
    ```console
-   $ git push && git push --tags
+   $ git push
    ```
 
-6. CI builds and publishes to PyPI automatically
+6. Push the tag:
+
+   ```console
+   $ git push --tags
+   ```
+
+7. CI builds and publishes to PyPI automatically
 
 For AI agents: do not create or push tags unless the user explicitly asks.
 Prepare the release files and commit only.
+
+[OIDC]: https://openid.net/developers/how-connect-works/
+[PyPI]: https://pypi.org/

docs/quickstart.md

@@ -50,7 +50,7 @@ $ uv add g
 
 ### Developmental releases
 
-New versions of g are published to PyPI as alpha, beta, or release candidates.
+New versions of g are published to [PyPI] as alpha, beta, or release candidates.
 In their versions you will see notification like `a1`, `b1`, and `rc1`, respectively.
 `1.10.0b4` would mean the 4th beta release of `1.10.0` before general availability.
 
@@ -120,6 +120,7 @@ For unreleased trunk builds, expect breakage:
 
 [pip]: https://pip.pypa.io/en/stable/
 [pipx]: https://pypa.github.io/pipx/docs/
+[PyPI]: https://pypi.org/
 [uv]: https://docs.astral.sh/uv/
 [uv-tools]: https://docs.astral.sh/uv/concepts/tools/
 [uvx]: https://docs.astral.sh/uv/guides/tools/