The docs site
The docs site is built with Astro and
Starlight and lives in docs/. Its pages are
Markdown files in docs/src/content/docs/. The sidebar is set in
docs/astro.config.mjs.
Prerequisites
Section titled “Prerequisites”Besides the tools in Local development, the site needs:
- Node.js 22.23.4 or later, the oldest version the site’s
Astro release supports and the one
docs/package.jsonrequires. CI and the git hooks use 24.22.3. - pnpm 10.34.5, the version
docs/package.jsonnames.corepack enablesets it up from that file, or install it withnpm install -g pnpm@10.34.5.
The site’s own packages are pinned in docs/pnpm-lock.yaml. The recipes below
install them from the lock file.
Preview the site
Section titled “Preview the site”just docsThis serves the site with live reload. Open the address it prints, which ends in
/pydelity/. Changes to pages show up as you save them.
Build and check it
Section titled “Build and check it”just docs-buildThis builds the site from the current tree into docs/dist/ and then checks
every internal link and #fragment in it. A broken link fails the build. CI
runs the same build and check on every pull request.
Reference pages
Section titled “Reference pages”The pages in docs/src/content/docs/reference/ are generated from pydelity’s
code by scripts/generate_reference_docs.py: the settings from the Pydantic
models, the command from Typer, the Python API from the docstrings, and each
output file from its schema. Don’t edit them by hand. Change the code or its
docstrings, then run:
just docs-referencejust lint runs this too, before formatting Markdown. CI regenerates the pages
and fails if they differ from what is committed, so a reference page can’t fall
behind the code.
Write a page
Section titled “Write a page”- Write pages in Markdown (
.md), with atitleanddescriptionin the front matter.just lint-markdownformats them with Prettier and checks them with markdownlint, and the git hook does the same on commit. - Link to other pages with relative links, such as
../../reference/cli/. The site is served at/pydelity/and each release at/pydelity/v/<version>/, and relative links work in both. - Add a new page to the sidebar in
docs/astro.config.mjs, except underreference/, whose pages are listed automatically. - Link to reference pages for exact names and fields rather than copying them, so there is one place to keep up to date.
Versions and publishing
Section titled “Versions and publishing”The published site has one version per release, from v0.1.0 on. The latest
release is at https://idinsight.github.io/pydelity/, and every release is also
at /pydelity/v/<version>/, with a version selector on each page.
To build all versions locally, fetch the tags and run the versioned build:
git fetch --tagscd docspnpm install --frozen-lockfilepnpm run build:versionspnpm run check-linksEach version’s pages come from its release tag (v<version>). The version
selector, styles and components come from the current checkout, so they are the
same on every version. The build fails when there is no release tag of v0.1.0 or
later.
The Docs workflow (.github/workflows/docs.yml) publishes the site to GitHub
Pages:
- Pull requests build the current tree and check its links. Nothing is published.
- Pushes to
main, release tags and manual runs build every released version. The site is published only when the package version onmainhas its release tag.
Because pages come from release tags, a docs change merged into main reaches
the published site with the next release.