Tighten docs cross-references

CHANGES

@@ -1,6 +1,6 @@
 # Changelog
 
-To install the unreleased g version, see [developmental releases](https://g.git-pull.com/quickstart.html#developmental-releases).
+To install the unreleased g version, see {ref}`developmental-releases`.
 
 [pip](https://pip.pypa.io/en/stable/):
 
@@ -12,7 +12,12 @@ $ pip install --user --upgrade --pre g
 
 ```console
 $ pipx install --suffix=@next 'g' --pip-args '\--pre' --force
-// Usage: g@next --help
+```
+
+Then use the suffixed command:
+
+```console
+$ g@next --help
 ```
 
 [uv](https://docs.astral.sh/uv/getting-started/features/#python-versions):
@@ -41,7 +46,7 @@ g 0.0.10 turns g's documentation into a usable CLI reference and moves the docs
 
 `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.
 
-The implementation preserves the existing {func}`g.run` test hook: in test mode the version path returns cleanly instead of exiting through `argparse`, so the behavior can be asserted without special subprocess handling.
+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)
 
@@ -67,6 +72,16 @@ The API page now uses card-style autodoc signatures and badge styling from `sphi
 - The manual CLI "Usage" section was renamed to "Usage examples" so it no longer collides with the argparse-generated `usage` anchor (#54).
 - Light and dark mode CSS for argparse metadata and header links now handles Furo's automatic theme mode correctly (#46).
 
+### Documentation
+
+#### Clearer paths through the documentation (#61)
+
+The docs now guide readers from install to first command, CLI behavior, or
+contributor material without requiring them to understand g's internals first.
+Command examples are easier to scan one action at a time, and cross-links from
+release notes, API details, and project pages take readers directly to the
+matching reference material.
+
 ### Development
 
 - Root `conftest.py` remains type-checked while the temporary docs-extension mypy path excludes only the extension-local `docs/_ext/conftest.py` case that caused duplicate module discovery (#46).
@@ -149,13 +164,13 @@ g 0.0.5 fixes the main user-facing failure mode outside a repository. Running `g
 
 ### Fixes
 
-#### Running outside a VCS directory no longer raises `AssertionError` (#24)
+#### Running outside a VCS directory no longer raises {exc}`AssertionError` (#24)
 
 When no `.git`, `.svn`, or `.hg` marker is found while walking upward from the current directory, g now reports that no VCS was found and returns without trying to spawn a subprocess. The test suite covers the non-repository case directly.
 
 ### Development
 
-The CLI test fixtures were rewritten into typed `NamedTuple` records, and the `G_IS_TEST` environment flag remains the path for asserting subprocess behavior without leaking `Popen` objects into user output (#24).
+The CLI test fixtures were rewritten into typed {class}`typing.NamedTuple` records, and the `G_IS_TEST` environment flag remains the path for asserting subprocess behavior without leaking {class}`subprocess.Popen` objects into user output (#24).
 
 ## g 0.0.4 (2024-03-24)
 
@@ -177,11 +192,11 @@ Poetry moved from `1.7.1` to `1.8.1`, and the CI helper actions were updated to
 
 ## g 0.0.3 (2023-12-09)
 
-g 0.0.3 tightens the development harness around the small CLI wrapper. The release moves more configuration into `pyproject.toml`, strengthens docs and lint expectations, and fixes the visible `Popen` repr that could appear after running `g`.
+g 0.0.3 tightens the development harness around the small CLI wrapper. The release moves more configuration into `pyproject.toml`, strengthens docs and lint expectations, and fixes the visible {class}`subprocess.Popen` repr that could appear after running `g`.
 
 ### Fixes
 
-#### `g` no longer prints a `Popen` representation after commands (#19)
+#### `g` no longer prints a {class}`subprocess.Popen` representation after commands (#19)
 
 {func}`g.run` now returns the subprocess only when `G_IS_TEST` is set. Normal CLI usage no longer appends output such as `<Popen: returncode: 1 args: ['git']>` after the delegated VCS command.
 

docs/api.md

@@ -1,5 +1,8 @@
 # Internal API
 
+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.
 ```

docs/cli/index.md

@@ -39,10 +39,22 @@ $ g status
 
 Is equivalent to:
 
+In a git repo:
+
+```console
+$ git status
+```
+
+In an svn repo:
+
+```console
+$ svn status
+```
+
+In an hg repo:
+
 ```console
-$ git status  # if in a git repo
-$ svn status  # if in an svn repo
-$ hg status   # if in an hg repo
+$ hg status
 ```
 
 (cli-main)=
@@ -60,8 +72,17 @@ $ hg status   # if in an hg repo
 
 ```console
 $ g status
+```
+
+```console
 $ g commit -m "Fix bug"
+```
+
+```console
 $ g log --oneline -10
+```
+
+```console
 $ g diff HEAD~1
 ```
 

docs/conf.py

@@ -36,8 +36,8 @@
         "sphinx_autodoc_argparse.exemplar",
     ],
     intersphinx_mapping={
-        "py": ("https://docs.python.org/", None),
-        "libvcs": ("http://libvcs.git-pull.com/", None),
+        "py": ("https://docs.python.org/3/", None),
+        "libvcs": ("https://libvcs.git-pull.com/", None),
     },
     linkcode_resolve=make_linkcode_resolve(g, about["__github__"]),
     html_favicon="_static/favicon.ico",

docs/index.md

@@ -37,7 +37,7 @@ $ pip install --user g
 $ uv tool install g
 ```
 
-See [Quickstart](quickstart.md) for all installation methods and first steps.
+See {doc}`quickstart` for all installation methods and first steps.
 
 ## At a glance
 

docs/project/code-style.md

@@ -1,21 +1,24 @@
 # Code Style
 
+Use this page when you are changing g itself and want the same local checks CI
+expects.
+
 ## Formatting
 
 g uses [ruff](https://github.com/astral-sh/ruff) for linting and formatting.
 
 ```console
-$ uv run ruff format .
+$ uv run ruff check . --fix
 ```
 
 ```console
-$ uv run ruff check . --fix
+$ uv run ruff format .
 ```
 
 ## Type Checking
 
 [mypy](https://mypy-lang.org/) is used for static type checking.
 
 ```console
-$ uv run mypy
+$ uv run mypy .
 ```

docs/project/contributing.md

@@ -1,10 +1,11 @@
 # Development
 
-[uv] is a required package to develop.
+Use this page when you want to change g itself. If you only want to install and
+run the command, start with {doc}`/quickstart`.
 
 ## Bootstrap the project
 
-Install and [git] and [uv]
+Install [git] and [uv].
 
 Clone:
 
@@ -27,9 +28,15 @@ $ uv sync --all-extras --dev
 
 ## Tests
 
-`uv run py.test`
+```console
+$ uv run py.test
+```
+
+The Makefile wrapper runs the same test command.
 
-Helpers: `make test`
+```console
+$ make test
+```
 
 ## Automatically run tests on file save
 
@@ -42,14 +49,15 @@ Helpers: `make test`
 
 Default preview server: http://localhost:8034
 
-[sphinx-autobuild] will automatically build the docs, watch for file changes and launch a server.
+[sphinx-autobuild] builds the docs, watches for file changes, and launches a
+server.
 
 From home directory: `make start_docs`
 From inside `docs/`: `make start`
 
 [sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild
 
-### Manual documentation (the hard way)
+### Manual documentation
 
 `cd docs/` and `make html` to build. `make serve` to start http server.
 
@@ -72,10 +80,10 @@ The project uses [ruff] to handle formatting, sorting imports and linting.
 uv:
 
 ```console
-$ uv run ruff
+$ uv run ruff check .
 ```
 
-If you setup manually:
+If you set up manually:
 
 ```console
 $ ruff check .
@@ -109,7 +117,7 @@ uv:
 $ uv run ruff check . --fix
 ```
 
-If you setup manually:
+If you set up manually:
 
 ```console
 $ ruff check . --fix
@@ -119,7 +127,7 @@ $ ruff check . --fix
 
 #### ruff format
 
-[ruff format] is used for formatting.
+Use [ruff format] for formatting.
 
 ````{tab} Command
 
@@ -129,7 +137,7 @@ uv:
 $ uv run ruff format .
 ```
 
-If you setup manually:
+If you set up manually:
 
 ```console
 $ ruff format .
@@ -147,7 +155,7 @@ $ make ruff_format
 
 ### mypy
 
-[mypy] is used for static type checking.
+Use [mypy] for static type checking.
 
 ````{tab} Command
 
@@ -157,7 +165,7 @@ uv:
 $ uv run mypy .
 ```
 
-If you setup manually:
+If you set up manually:
 
 ```console
 $ mypy .
@@ -185,14 +193,9 @@ requires [`entr(1)`].
 ## Releasing
 
 [uv] handles virtualenv creation, package requirements, versioning,
-building, and publishing. Therefore there is no setup.py or requirements files.
-
-Update `__version__` in `__about__.py` and `pyproject.toml`::
+building, and publishing. There is no `setup.py` or requirements file.
 
-    git commit -m 'build(g): Tag v0.1.1'
-    git tag v0.1.1
-    git push
-    git push --tags
+See {doc}`/project/releasing` before preparing a release.
 
 [uv]: https://github.com/astral-sh/uv
 [entr(1)]: http://eradman.com/entrproject/

docs/project/releasing.md

@@ -2,22 +2,29 @@
 
 ## Release Process
 
-Releases are triggered by git tags and published to PyPI via OIDC trusted publishing.
+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.
 
 1. Update `CHANGES` with the release notes
 
-2. Bump version in `src/g/__about__.py` (or wherever version is defined -- check pyproject.toml)
+2. Bump the version in `src/g/__about__.py` and `pyproject.toml`
 
-3. Tag:
+3. Commit the release files with the subject `Tag v<version>`
+
+4. Tag:
 
    ```console
    $ git tag v<version>
    ```
 
-4. Push:
+5. Push the branch and tag:
 
    ```console
    $ git push && git push --tags
    ```
 
-5. CI builds and publishes to PyPI automatically
+6. 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.

docs/quickstart.md

@@ -4,13 +4,14 @@
 
 ## Installation
 
-For latest official version:
+Install g once, then run `g` where you already run `git`, `svn`, or `hg`.
+Use one of these commands for the latest official version.
 
 ```console
 $ pip install --user g
 ```
 
-Or install with [uv](https://docs.astral.sh/uv/):
+Or install it as a [uv] tool:
 
 ```console
 $ uv tool install g
@@ -28,13 +29,13 @@ Run g once without installing globally:
 $ uvx g
 ```
 
-Upgrading:
+Upgrade an existing install the same way.
 
 ```console
 $ pip install --user --upgrade g
 ```
 
-Or with uv:
+With [uv]:
 
 ```console
 $ uv tool upgrade g
@@ -62,7 +63,12 @@ In their versions you will see notification like `a1`, `b1`, and `rc1`, respecti
 
   ```console
   $ pipx install --suffix=@next 'g' --pip-args '\--pre' --force
-  // Usage: g@next --help
+  ```
+
+  Then use the suffixed command:
+
+  ```console
+  $ g@next --help
   ```
 
 - [uv tool install][uv-tools]\:
@@ -83,7 +89,7 @@ In their versions you will see notification like `a1`, `b1`, and `rc1`, respecti
   $ uvx --from 'g' --prerelease allow g
   ```
 
-via trunk (can break easily):
+For unreleased trunk builds, expect breakage:
 
 - [pip]\:
 

justfile

@@ -0,0 +1,2 @@
+build-docs:
+    just -f docs/justfile html