docs(redesign): restructure to Library Skeleton (#451)

Restructure django-docutils documentation to the Library Skeleton.
topics/ section created (template_tag, template_filter, class_based_view,
faq moved from root). API index cards. project/ section. Standalone
composed homepage. 4 redirects. sphinx-design added.

Author: tony

docs/api/index.md

@@ -8,20 +8,48 @@
 
 :::
 
-## Inside
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Exceptions
+:link: exc
+:link-type: doc
+Exception definitions for django-docutils.
+:::
+
+:::{grid-item-card} Views
+:link: views
+:link-type: doc
+`DocutilsView` and response classes.
+:::
+
+:::{grid-item-card} Lib
+:link: lib/index
+:link-type: doc
+Publisher, roles, directives, writers, and transforms.
+:::
+
+:::{grid-item-card} Template Engine
+:link: template
+:link-type: doc
+`DocutilsTemplates` backend for Django.
+:::
+
+:::{grid-item-card} Template Tags
+:link: templatetags/index
+:link-type: doc
+`{% rst %}` tag and `rst` filter internals.
+:::
+
+::::
 
 ```{toctree}
 :maxdepth: 1
+:hidden:
 
 exc
 views
 lib/index
 template
 templatetags/index
 ```
-
-## Common
-
-### Exceptions
-
-See {doc}`/api/exc` for exception definitions.

docs/conf.py

@@ -47,8 +47,10 @@
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
     "myst_parser",
+    "sphinx_design",
     "linkify_issues",
 ]
+myst_heading_anchors = 4
 myst_enable_extensions = [
     "colon_fence",
     "substitution",

docs/index.md

@@ -1,25 +1,70 @@
 (index)=
 
-```{include} ../README.md
+# django-docutils
 
+Docutils (reStructuredText) support for Django templates, views, and template engines.
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Quickstart
+:link: quickstart
+:link-type: doc
+Install and render your first RST snippet in 5 minutes.
+:::
+
+:::{grid-item-card} Topics
+:link: topics/index
+:link-type: doc
+Template tags, template filters, class-based views, and FAQ.
+:::
+
+:::{grid-item-card} API Reference
+:link: api/index
+:link-type: doc
+Every public class, function, and exception.
+:::
+
+:::{grid-item-card} Contributing
+:link: project/index
+:link-type: doc
+Development setup, code style, release process.
+:::
+
+::::
+
+## Install
+
+```console
+$ pip install django-docutils
 ```
 
-```{toctree}
-:maxdepth: 2
-:hidden:
+```console
+$ uv add django-docutils
+```
 
-quickstart
-template_tag
-template_filter
-class_based_view
-faq
+See [Quickstart](quickstart.md) for configuration and first steps.
+
+## At a glance
+
+```django
+{% load django_docutils %}
+
+{% rst %}
+Title
+=====
+
+*reStructuredText* rendered to HTML inside a Django template.
+{% endrst %}
 ```
 
 ```{toctree}
-:caption: Project
 :hidden:
 
+quickstart
+topics/index
 api/index
+project/index
 history
 GitHub <https://github.com/tony/django-docutils>
 ```

docs/project/code-style.md

@@ -0,0 +1,30 @@
+# Code Style
+
+## Formatting
+
+django-docutils 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/) with [django-stubs](https://github.com/typeddjango/django-stubs) is enforced across `src/` and `tests/`.
+
+```console
+$ uv run mypy
+```
+
+## Docstrings
+
+Follow [NumPy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) for all public functions and methods.
+
+## Imports
+
+- Always include `from __future__ import annotations` at the top of Python files.
+- Use `import typing as t` and access via namespace: `t.Optional`, `t.Dict`, etc.

docs/project/contributing.md

@@ -0,0 +1,49 @@
+# Development
+
+Install [git](https://git-scm.com/) and [uv](https://github.com/astral-sh/uv).
+
+Clone:
+
+```console
+$ git clone https://github.com/tony/django-docutils.git
+```
+
+```console
+$ cd django-docutils
+```
+
+Install packages:
+
+```console
+$ uv sync --all-extras --dev
+```
+
+## Running Tests
+
+```console
+$ uv run pytest
+```
+
+Run a single test file:
+
+```console
+$ uv run pytest tests/test_template.py
+```
+
+Watch tests:
+
+```console
+$ uv run ptw .
+```
+
+## Building Docs
+
+```console
+$ uv run sphinx-build docs docs/_build
+```
+
+Live-reload:
+
+```console
+$ uv run sphinx-autobuild docs docs/_build
+```

docs/project/index.md

@@ -0,0 +1,36 @@
+(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, NumPy docstrings, import conventions.
+:::
+
+:::{grid-item-card} Releasing
+:link: releasing
+:link-type: doc
+Release checklist and version policy.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+
+contributing
+code-style
+releasing
+```

docs/project/releasing.md

@@ -0,0 +1,32 @@
+# Releasing
+
+## Version Policy
+
+django-docutils is pre-1.0. Minor version bumps may include breaking changes.
+Users should pin to `>=0.x,<0.y`.
+
+## Release Process
+
+Releases are triggered by git tags and published to PyPI via trusted publishing.
+
+1. Update `CHANGES` with the release notes
+
+2. Bump version in `src/django_docutils/__about__.py`
+
+3. Commit:
+
+   ```console
+   $ git commit -m "django-docutils <version>"
+   ```
+
+4. Tag:
+
+   ```console
+   $ git tag v<version>
+   ```
+
+5. Push:
+
+   ```console
+   $ git push && git push --tags
+   ```

docs/redirects.txt

@@ -1,3 +1,7 @@
 "usage.rst" "quickstart.md"
 # "api.md" "api/index.md"  # dirhtml: same output path
 "django_view.rst" "class_based_view.md"
+"template_tag.md" "topics/template_tag.md"
+"template_filter.md" "topics/template_filter.md"
+"class_based_view.md" "topics/class_based_view.md"
+"faq.md" "topics/faq.md"