Merge pull request #65 from git-pull/doc-redesign-spring-2026

docs(redesign): restructure documentation to Library Skeleton pattern

Author: tony

docs/conf.py

@@ -39,9 +39,11 @@
     "sphinx_copybutton",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
+    "sphinx_design",
     "myst_parser",
     "linkify_issues",
 ]
+myst_heading_anchors = 4
 myst_enable_extensions = [
     "colon_fence",
     "substitution",

docs/developing.md

@@ -5,6 +5,17 @@
 
 Built on {mod}`doctest`.
 
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} pytest plugin
+:link: pytest
+:link-type: doc
+Run doctests in `.rst` and `.md` files via pytest.
+:::
+
+::::
+
 :::{note}
 
 Before you begin, acquaint yourself with:

docs/doctest/index.md

@@ -1,22 +1,70 @@
 (index)=
 
-```{include} ../README.md
+# gp-libs
 
+Test and documentation utilities for [git-pull](https://github.com/git-pull) projects.
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Quickstart
+:link: quickstart
+:link-type: doc
+Install and get started in minutes.
+:::
+
+:::{grid-item-card} doctest_docutils
+:link: doctest/index
+:link-type: doc
+Run doctests in reStructuredText and Markdown files.
+:::
+
+:::{grid-item-card} linkify_issues
+:link: linkify_issues/index
+:link-type: doc
+Automatically link `#123` to GitHub issues in Sphinx docs.
+:::
+
+:::{grid-item-card} Contributing
+:link: project/index
+:link-type: doc
+Development setup, code style, release process.
+:::
+
+::::
+
+## Install
+
+```console
+$ pip install gp-libs
 ```
 
-```{toctree}
-:hidden:
+```console
+$ uv add gp-libs
+```
 
-quickstart
-doctest/index
-linkify_issues/index
+## At a glance
+
+Run doctests in Markdown and reStructuredText files:
+
+```console
+$ python -m doctest_docutils README.md -v
+```
+
+Auto-link issue references in Sphinx documentation:
+
+```python
+# conf.py
+extensions = ["linkify_issues"]
+issue_url_tpl = "https://github.com/myorg/myrepo/issues/{issue_id}"
 ```
 
 ```{toctree}
-:caption: Project
 :hidden:
 
-developing
+quickstart
+doctest/index
+linkify_issues/index
+project/index
 history
-GitHub <https://github.com/git-pull/gp-libs>
 ```

docs/index.md

@@ -0,0 +1,26 @@
+# Code Style
+
+## Formatting
+
+gp-libs uses [ruff](https://github.com/astral-sh/ruff) for both linting and formatting.
+
+```console
+$ uv run ruff format .
+```
+
+```console
+$ uv run ruff check . --fix --show-fixes
+```
+
+## Type Checking
+
+Strict [mypy](https://mypy-lang.org/) is enforced across `src/` and `tests/`.
+
+```console
+$ uv run mypy .
+```
+
+## Docstrings
+
+Follow [NumPy docstring style](https://numpydoc.readthedocs.io/en/latest/format.html)
+for all public functions, methods, and classes.

docs/project/code-style.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Install [git] and [uv].
+
+Clone:
+
+```console
+$ git clone https://github.com/git-pull/gp-libs.git
+```
+
+```console
+$ cd gp-libs
+```
+
+Install packages:
+
+```console
+$ uv sync --all-extras --dev
+```
+
+## Tests
+
+```console
+$ uv run py.test
+```
+
+### Automatically run tests on file save
+
+1. `make start` (via [pytest-watcher])
+2. `make watch_test` (requires installing [entr(1)])
+
+[pytest-watcher]: https://github.com/olzhasar/pytest-watcher
+
+## Documentation
+
+Default preview server: http://localhost:8034
+
+[sphinx-autobuild] will automatically build the docs, watch for file changes and launch 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)
+
+`cd docs/` and `make html` to build. `make serve` to start http server.
+
+Helpers:
+`make build_docs`, `make serve_docs`
+
+Rebuild docs on file change: `make watch_docs` (requires [entr(1)])
+
+Rebuild docs and run server via one terminal: `make dev_docs` (requires above, and a
+`make(1)` with `-J` support, e.g. GNU Make)
+
+[git]: https://git-scm.com/
+[uv]: https://github.com/astral-sh/uv
+[entr(1)]: http://eradman.com/entrproject/
+[`entr(1)`]: http://eradman.com/entrproject/