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

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

Author: tony

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/developing.md docs/project/contributing.mddocs/developing.md renamed to docs/project/contributing.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/index.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/project/releasing.md

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