From 896f399c72845f3640bf7a50925d4acc6908b440 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 4 Jul 2026 21:52:23 -0500 Subject: [PATCH 1/2] docs(style): tighten docs crossrefs why: Docs guidance requires first-mention links, valid console examples, and concept-first reader framing across the rendered site. what: - Link rendered docs objects and page references with MyST/Sphinx roles - Refresh quickstart, contributor, code-style, release, and API prose - Add the root just build-docs entrypoint used by the required gate --- CHANGES | 19 ++++++++++------ docs/api.md | 3 +++ docs/cli/index.md | 27 +++++++++++++++++++--- docs/conf.py | 4 ++-- docs/index.md | 2 +- docs/project/code-style.md | 9 +++++--- docs/project/contributing.md | 43 +++++++++++++++++++----------------- docs/project/releasing.md | 17 +++++++++----- docs/quickstart.md | 18 ++++++++++----- justfile | 2 ++ 10 files changed, 97 insertions(+), 47 deletions(-) create mode 100644 justfile diff --git a/CHANGES b/CHANGES index bc66ade..045135f 100644 --- a/CHANGES +++ b/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) @@ -149,13 +154,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 +182,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 `` after the delegated VCS command. diff --git a/docs/api.md b/docs/api.md index 8c3e0f5..ee672bf 100644 --- a/docs/api.md +++ b/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. ``` diff --git a/docs/cli/index.md b/docs/cli/index.md index 982e0ab..5722390 100644 --- a/docs/cli/index.md +++ b/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 ``` diff --git a/docs/conf.py b/docs/conf.py index 86c5897..8bc7022 100644 --- a/docs/conf.py +++ b/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", diff --git a/docs/index.md b/docs/index.md index a91393d..2aa53b3 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/project/code-style.md b/docs/project/code-style.md index b7d64e4..a10b837 100644 --- a/docs/project/code-style.md +++ b/docs/project/code-style.md @@ -1,15 +1,18 @@ # 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 @@ -17,5 +20,5 @@ $ uv run ruff check . --fix [mypy](https://mypy-lang.org/) is used for static type checking. ```console -$ uv run mypy +$ uv run mypy . ``` diff --git a/docs/project/contributing.md b/docs/project/contributing.md index 37f4002..3debe69 100644 --- a/docs/project/contributing.md +++ b/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/ diff --git a/docs/project/releasing.md b/docs/project/releasing.md index cf041aa..756415c 100644 --- a/docs/project/releasing.md +++ b/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` + +4. Tag: ```console $ git tag v ``` -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. diff --git a/docs/quickstart.md b/docs/quickstart.md index 504fb30..2467fa7 100644 --- a/docs/quickstart.md +++ b/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]\: diff --git a/justfile b/justfile new file mode 100644 index 0000000..8e9adc6 --- /dev/null +++ b/justfile @@ -0,0 +1,2 @@ +build-docs: + just -f docs/justfile html From 34d7a9c2bb7333da6a88b128a5d5942a0868c59a Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 4 Jul 2026 22:02:11 -0500 Subject: [PATCH 2/2] docs(changelog): add docs cleanup note why: The docs cleanup should appear in the release notes as a reader-facing improvement, not just as implementation detail in the PR. what: - Add a high-level Documentation entry for clearer docs paths - Describe the reader outcome without listing internal link mechanics --- CHANGES | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CHANGES b/CHANGES index 045135f..6429216 100644 --- a/CHANGES +++ b/CHANGES @@ -72,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).