docs(redesign): restructure documentation to CLI Frontend Skeleton pattern

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.
 

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"]
 

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 <https://github.com/vcs-python/g>
 ```

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
+```

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
+```

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<version>
+   ```
+
+4. Push:
+
+   ```console
+   $ git push && git push --tags
+   ```
+
+5. CI builds and publishes to PyPI automatically

docs/redirects.txt

@@ -0,0 +1 @@
+"developing.md" "project/contributing.md"

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",