Merge pull request #344 from cihai/doc-redesign-spring-2026

docs(redesign) — CLI Frontend Skeleton pattern (#344)

Restructure cihai-cli documentation to the CLI Frontend Skeleton.
Standalone composed homepage with command output examples. CLI index
cards. API demoted from homepage. project/ section. sphinx-design added.

Author: tony

docs/cli/index.md

@@ -1,9 +1,33 @@
 (cli)=
 
-# Commands
+# CLI Reference
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} cihai info
+:link: info
+:link-type: doc
+Look up a CJK character by glyph or codepoint.
+:::
+
+:::{grid-item-card} cihai reverse
+:link: reverse
+:link-type: doc
+Search definitions for a given term.
+:::
+
+:::{grid-item-card} Completions
+:link: completion
+:link-type: doc
+Shell completion for bash, zsh, and tcsh.
+:::
+
+::::
 
 ```{toctree}
 :caption: General
+:maxdepth: 1
 
 info
 reverse

docs/conf.py

@@ -38,12 +38,15 @@
     "argparse_exemplar",  # Custom sphinx-argparse replacement
     "sphinx_inline_tabs",
     "sphinx_copybutton",
+    "sphinx_design",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
     "myst_parser",
     "linkify_issues",
 ]
 
+myst_heading_anchors = 4
+
 myst_enable_extensions = [
     "colon_fence",
     "substitution",

docs/index.md

@@ -1,26 +1,75 @@
 (index)=
 
-```{include} ../README.md
+# cihai-cli
 
+Command line frontend for the [cihai](https://cihai.git-pull.com/) CJK language library.
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Quickstart
+:link: quickstart
+:link-type: doc
+Install and look up your first character.
+:::
+
+:::{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 cihai-cli
 ```
 
-## Contents
+```console
+$ uv tool install cihai-cli
+```
 
-```{toctree}
-:maxdepth: 2
+## At a glance
 
-quickstart
-cli/index
+Look up a CJK character:
 
+```console
+$ cihai info 好
 ```
 
+```
+char: 好
+kDefinition: good, excellent, fine; well
+kMandarin: hǎo
+```
+
+Search definitions:
+
+```console
+$ cihai reverse library
+```
+
+```
+圕: library
+```
+
+Data is downloaded automatically on first use via [cihai](https://cihai.git-pull.com/).
+
 ```{toctree}
-:caption: Project
 :hidden:
 
+quickstart
+cli/index
 api
+project/index
 history
 migration
-Developer Guide <https://cihai.git-pull.com/contributing/>
-GitHub <https://github.com/cihai/cihai-cli>
 ```

docs/project/code-style.md

@@ -0,0 +1,31 @@
+# Code Style
+
+## Formatting
+
+cihai-cli 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.
+
+```console
+$ uv run mypy
+```
+
+## Docstrings
+
+All public functions and methods use NumPy-style docstrings.
+
+## Imports
+
+- Standard library: namespace imports (`import pathlib`, not `from pathlib import Path`)
+- Typing: `import typing as t`, access via `t.Optional`, `t.NamedTuple`, etc.
+- All files: `from __future__ import annotations`

docs/project/contributing.md

@@ -0,0 +1,28 @@
+# Contributing
+
+cihai-cli follows the cihai project's contributing guidelines.
+
+See the [cihai contributing guide](https://cihai.git-pull.com/contributing/) for
+development setup, running tests, and submitting pull requests.
+
+## Quick setup
+
+Clone and install in development mode:
+
+```console
+$ git clone https://github.com/cihai/cihai-cli.git
+```
+
+```console
+$ cd cihai-cli
+```
+
+```console
+$ uv sync --group dev
+```
+
+Run the tests:
+
+```console
+$ uv run pytest
+```

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
+How to get involved and submit changes.
+:::
+
+:::{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,29 @@
+# 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/cihai_cli/__about__.py`
+
+3. Commit:
+
+   ```console
+   $ git commit -m "cihai-cli <version>"
+   ```
+
+4. Tag:
+
+   ```console
+   $ git tag v<version>
+   ```
+
+5. Push:
+
+   ```console
+   $ git push && git push --tags
+   ```
+
+6. CI builds and publishes to PyPI automatically via trusted publishing

pyproject.toml

@@ -71,6 +71,7 @@ dev = [
   "gp-libs",
   "sphinx-autobuild",
   "sphinx-autodoc-typehints",
+  "sphinx-design",
   "sphinx-inline-tabs",
   "sphinxext-opengraph",
   "sphinx-copybutton",
@@ -104,6 +105,7 @@ docs = [
   "gp-libs",
   "sphinx-autobuild",
   "sphinx-autodoc-typehints",
+  "sphinx-design",
   "sphinx-inline-tabs",
   "sphinxext-opengraph",
   "sphinx-copybutton",