From e27c421151c25df4bb9c92d16dcdef8711cf9e80 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Tue, 24 Mar 2026 18:12:49 -0500 Subject: [PATCH 1/2] py(deps[docs]): add sphinx-design, annotate doc dependencies with site URLs why: sphinx-design is needed for grid cards in the documentation landing pages and section indexes. Doc-site URLs added as inline comments for quick reference when managing dependencies. what: - Add sphinx-design to docs and dev dependency groups - Annotate all doc dependencies with their documentation URLs --- pyproject.toml | 2 ++ uv.lock | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 245be67..1417714 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -70,6 +70,7 @@ dev = [ "sphinxext-rediraffe", "sphinx-argparse", "myst-parser", + "sphinx-design", # https://sphinx-design.readthedocs.io/ "linkify-it-py", # Testing "gp-libs", @@ -103,6 +104,7 @@ docs = [ "sphinxext-rediraffe", "myst-parser", "linkify-it-py", + "sphinx-design", # https://sphinx-design.readthedocs.io/ ] testing = [ "gp-libs", diff --git a/uv.lock b/uv.lock index 5086b0e..137c28b 100644 --- a/uv.lock +++ b/uv.lock @@ -413,6 +413,8 @@ dev = [ { name = "sphinx-autodoc-typehints", version = "3.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx-autodoc-typehints", version = "3.5.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, { name = "sphinx-copybutton" }, + { name = "sphinx-design", version = "0.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx-design", version = "0.7.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, { name = "sphinx-inline-tabs" }, { name = "sphinxext-opengraph" }, { name = "sphinxext-rediraffe" }, @@ -434,6 +436,8 @@ docs = [ { name = "sphinx-autodoc-typehints", version = "3.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx-autodoc-typehints", version = "3.5.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, { name = "sphinx-copybutton" }, + { name = "sphinx-design", version = "0.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx-design", version = "0.7.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, { name = "sphinx-inline-tabs" }, { name = "sphinxext-opengraph" }, { name = "sphinxext-rediraffe" }, @@ -479,6 +483,7 @@ dev = [ { name = "sphinx-autobuild" }, { name = "sphinx-autodoc-typehints" }, { name = "sphinx-copybutton" }, + { name = "sphinx-design" }, { name = "sphinx-inline-tabs" }, { name = "sphinxext-opengraph" }, { name = "sphinxext-rediraffe" }, @@ -496,6 +501,7 @@ docs = [ { name = "sphinx-autobuild" }, { name = "sphinx-autodoc-typehints" }, { name = "sphinx-copybutton" }, + { name = "sphinx-design" }, { name = "sphinx-inline-tabs" }, { name = "sphinxext-opengraph" }, { name = "sphinxext-rediraffe" }, @@ -1427,6 +1433,37 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/9e/48/1ea60e74949eecb12cdd6ac43987f9fd331156388dcc2319b45e2ebb81bf/sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e", size = 13343, upload-time = "2023-04-14T08:10:20.844Z" }, ] +[[package]] +name = "sphinx-design" +version = "0.6.1" +source = { registry = "https://pypi.org/simple" } +resolution-markers = [ + "python_full_version < '3.11'", +] +dependencies = [ + { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/2b/69/b34e0cb5336f09c6866d53b4a19d76c227cdec1bbc7ac4de63ca7d58c9c7/sphinx_design-0.6.1.tar.gz", hash = "sha256:b44eea3719386d04d765c1a8257caca2b3e6f8421d7b3a5e742c0fd45f84e632", size = 2193689, upload-time = "2024-08-02T13:48:44.277Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c6/43/65c0acbd8cc6f50195a3a1fc195c404988b15c67090e73c7a41a9f57d6bd/sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c", size = 2215338, upload-time = "2024-08-02T13:48:42.106Z" }, +] + +[[package]] +name = "sphinx-design" +version = "0.7.0" +source = { registry = "https://pypi.org/simple" } +resolution-markers = [ + "python_full_version >= '3.12'", + "python_full_version == '3.11.*'", +] +dependencies = [ + { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/13/7b/804f311da4663a4aecc6cf7abd83443f3d4ded970826d0c958edc77d4527/sphinx_design-0.7.0.tar.gz", hash = "sha256:d2a3f5b19c24b916adb52f97c5f00efab4009ca337812001109084a740ec9b7a", size = 2203582, upload-time = "2026-01-19T13:12:53.297Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/30/cf/45dd359f6ca0c3762ce0490f681da242f0530c49c81050c035c016bfdd3a/sphinx_design-0.7.0-py3-none-any.whl", hash = "sha256:f82bf179951d58f55dca78ab3706aeafa496b741a91b1911d371441127d64282", size = 2220350, upload-time = "2026-01-19T13:12:51.077Z" }, +] + [[package]] name = "sphinx-inline-tabs" version = "2025.12.21.14" From 10b20055668a7fb18a4f1e4b7344ff540f82e33e Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Tue, 24 Mar 2026 18:12:49 -0500 Subject: [PATCH 2/2] docs(redesign): restructure documentation to CLI Frontend Skeleton pattern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit why: The landing page dumped the README with no visual navigation. No grid cards, no responsive layout, no contributor section. The sidebar was a flat toctree with no hierarchy. what: Landing page: - Compose standalone homepage with one-sentence hero, responsive 1x3 grid cards (Quickstart, CLI Reference, Contributing), install snippet (pip + uv), and "At a glance" example showing `g status` - Remove README {include} entirely Structure: - Create project/ section with grid cards: contributing.md (moved from developing.md), code-style.md, releasing.md - Add grid cards to cli/index.md for command navigation Dependencies: - Add sphinx-design to docs and dev dependency groups - Add sphinx_design extension and myst_heading_anchors = 4 to conf.py Redirects: - developing.md → project/contributing.md --- docs/cli/index.md | 19 ++++++- docs/conf.py | 2 + docs/index.md | 52 ++++++++++++++++--- docs/project/code-style.md | 21 ++++++++ .../contributing.md} | 0 docs/project/index.md | 30 +++++++++++ docs/project/releasing.md | 23 ++++++++ docs/redirects.txt | 1 + 8 files changed, 139 insertions(+), 9 deletions(-) create mode 100644 docs/project/code-style.md rename docs/{developing.md => project/contributing.md} (100%) create mode 100644 docs/project/index.md create mode 100644 docs/project/releasing.md diff --git a/docs/cli/index.md b/docs/cli/index.md index 7348c42..932d9b2 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1,6 +1,23 @@ (cli)= -# CLI +# CLI Reference + +::::{grid} 1 1 2 2 +:gutter: 2 2 3 3 + +:::{grid-item-card} g +:link: #command +:link-type: url +Proxy to your repo's VCS command. +::: + +:::{grid-item-card} Supported VCS +:link: #supported-vcs +:link-type: url +git, svn, and hg detection. +::: + +:::: g is a minimal CLI wrapper that proxies to your current directory's VCS command. diff --git a/docs/conf.py b/docs/conf.py index ce30da3..4031096 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,6 +43,7 @@ "myst_parser", "linkify_issues", "argparse_exemplar", + "sphinx_design", ] myst_enable_extensions = [ "colon_fence", @@ -51,6 +52,7 @@ "strikethrough", "linkify", ] +myst_heading_anchors = 4 templates_path = ["_templates"] diff --git a/docs/index.md b/docs/index.md index 7ab0dcb..b175e00 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,58 @@ (index)= -```{include} ../README.md +# g +A tiny CLI wrapper for git, svn, and hg -- auto-detects your repo type and proxies commands. + +::::{grid} 1 2 3 3 +:gutter: 2 2 3 3 + +:::{grid-item-card} Quickstart +:link: quickstart +:link-type: doc +Install and run your first command. +::: + +:::{grid-item-card} CLI Reference +:link: cli/index +:link-type: doc +Every command, flag, and option. +::: + +:::{grid-item-card} Contributing +:link: project/index +:link-type: doc +Development setup, code style, and releases. +::: + +:::: + +## Install + +```console +$ pip install --user g ``` -```{toctree} -:hidden: +```console +$ uv tool install g +``` -quickstart -cli/index +See [Quickstart](quickstart.md) for all installation methods and first steps. + +## At a glance + +```console +$ 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`. + ```{toctree} -:caption: Project :hidden: +quickstart +cli/index api -developing +project/index history -GitHub ``` diff --git a/docs/project/code-style.md b/docs/project/code-style.md new file mode 100644 index 0000000..b7d64e4 --- /dev/null +++ b/docs/project/code-style.md @@ -0,0 +1,21 @@ +# Code Style + +## Formatting + +g uses [ruff](https://github.com/astral-sh/ruff) for linting and formatting. + +```console +$ uv run ruff format . +``` + +```console +$ uv run ruff check . --fix +``` + +## Type Checking + +[mypy](https://mypy-lang.org/) is used for static type checking. + +```console +$ uv run mypy +``` diff --git a/docs/developing.md b/docs/project/contributing.md similarity index 100% rename from docs/developing.md rename to docs/project/contributing.md diff --git a/docs/project/index.md b/docs/project/index.md new file mode 100644 index 0000000..d292516 --- /dev/null +++ b/docs/project/index.md @@ -0,0 +1,30 @@ +(project)= + +# Project + +Information for contributors and maintainers. + +::::{grid} 1 1 2 2 +:gutter: 2 2 3 3 + +:::{grid-item-card} Contributing +:link: contributing +:link-type: doc +Development setup, running tests, submitting PRs. +::: + +:::{grid-item-card} Code Style +:link: code-style +:link-type: doc +Ruff, mypy, and import conventions. +::: + +:::: + +```{toctree} +:hidden: + +contributing +code-style +releasing +``` diff --git a/docs/project/releasing.md b/docs/project/releasing.md new file mode 100644 index 0000000..cf041aa --- /dev/null +++ b/docs/project/releasing.md @@ -0,0 +1,23 @@ +# Releasing + +## Release Process + +Releases are triggered by git tags and published to PyPI via OIDC trusted publishing. + +1. Update `CHANGES` with the release notes + +2. Bump version in `src/g/__about__.py` (or wherever version is defined -- check pyproject.toml) + +3. Tag: + + ```console + $ git tag v + ``` + +4. Push: + + ```console + $ git push && git push --tags + ``` + +5. CI builds and publishes to PyPI automatically diff --git a/docs/redirects.txt b/docs/redirects.txt index e69de29..ab45772 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -0,0 +1 @@ +"developing.md" "project/contributing.md"