From b0e90a2b7030ebd71d7e4af08b51382942107315 Mon Sep 17 00:00:00 2001 From: Tai Sakuma Date: Sun, 22 Mar 2026 12:13:26 -0400 Subject: [PATCH 1/2] docs: add badges to README Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index 784ad8f..1d551d8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,23 @@ # improved-octo-fortnight +[![GitHub Release][release-badge]][release-url] +[![GitHub Pages][pages-badge]][pages-url] + +[![Deploy dev docs][dev-badge]][dev-url] +[![Deploy release docs][release-docs-badge]][release-docs-url] +[![Deploy docs preview][preview-badge]][preview-url] + +[release-badge]: https://img.shields.io/github/v/release/TaiSakuma/improved-octo-fortnight +[release-url]: https://github.com/TaiSakuma/improved-octo-fortnight/releases/latest +[pages-badge]: https://img.shields.io/website?url=https://taisakuma.github.io/improved-octo-fortnight/ +[pages-url]: https://taisakuma.github.io/improved-octo-fortnight/ +[dev-badge]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-dev.yml/badge.svg +[dev-url]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-dev.yml +[release-docs-badge]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-release.yml/badge.svg +[release-docs-url]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-release.yml +[preview-badge]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-pr-preview.yml/badge.svg +[preview-url]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-pr-preview.yml + A reference implementation of a documentation workflow using [zensical](https://zensical.org/) and GitHub Pages. - [latest](https://taisakuma.github.io/improved-octo-fortnight/latest/) From aa2e7670b8a40e4784cfe85f755acc1a2cbd9a0d Mon Sep 17 00:00:00 2001 From: Tai Sakuma Date: Sun, 22 Mar 2026 14:39:38 -0400 Subject: [PATCH 2/2] docs: rewrite README and add MIT license Co-Authored-By: Claude Opus 4.6 (1M context) --- LICENSE | 21 +++++++++++++++++ README.md | 70 +++++++++++++++++++++++++++---------------------------- 2 files changed, 56 insertions(+), 35 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ecd8768 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Tai Sakuma + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 1d551d8..8dba143 100644 --- a/README.md +++ b/README.md @@ -18,59 +18,59 @@ [preview-badge]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-pr-preview.yml/badge.svg [preview-url]: https://github.com/TaiSakuma/improved-octo-fortnight/actions/workflows/docs-pr-preview.yml -A reference implementation of a documentation workflow using [zensical](https://zensical.org/) and GitHub Pages. +A reference implementation of documentation workflows. -- [latest](https://taisakuma.github.io/improved-octo-fortnight/latest/) -- [dev](https://taisakuma.github.io/improved-octo-fortnight/dev/) +📚 [Demo site](https://taisakuma.github.io/improved-octo-fortnight/) ## Features -- **Versioned docs** -- Release docs at `//`, dev docs at `/dev/`, and a `/latest/` alias -- **PR previews** -- Every PR gets a preview deployment at `/pr//` with an automatic comment linking to it -- **PR cleanup** -- Preview deployments are removed when PRs are closed -- **Version index** -- An auto-generated root `index.html` lists all available versions -- **Deploy verification** -- The preview URL is polled before posting the PR comment; a note is added if the site isn't ready yet -- **Custom domain support** -- Works with both default GitHub Pages URLs and custom domains -- **API reference** -- Auto-generated from Python docstrings using [mkdocstrings](https://mkdocstrings.github.io/). Add `:::` directives in Markdown to render any module (see `docs/api.md` for an example) +### Content -## How it works +- Built with [zensical](https://zensical.org/) +- API reference auto-generated using [mkdocstrings](https://mkdocstrings.github.io/) -Documentation is built with [zensical](https://zensical.org/) and deployed by pushing subdirectories to a `gh-pages` branch. Four workflows handle the different deployment scenarios: +This repo documents a Python package. The setup should work for other languages with minor modifications. -| Workflow | Trigger | Deploys to | -| --------------------- | -------------------------------- | ----------------------------------------- | -| `docs-dev.yml` | Push to `main` | `/dev/` | -| `docs-release.yml` | Release (via changelog workflow) | `//` + `/latest/` + `index.html` | -| `docs-pr-preview.yml` | PR opened/updated (incl. forks) | `/pr//` | -| `docs-pr-cleanup.yml` | PR closed | removes `/pr//` | +### Deployment -The `gh-pages` branch has the following structure: +- Deployed to [GitHub Pages](https://pages.github.com/) via [GitHub + Actions](https://github.com/features/actions) +- Separate docs for each release and development branch +- Docs preview for each PR -``` -gh-pages -├── .nojekyll +## GitHub Pages structure + +The deployed site is structured as follows: + +```text +/ ├── index.html # auto-generated version index ├── latest/ # copy of the latest release ├── dev/ # built from main -├── 0.2.1/ # release versions -├── 0.2.0/ +├── 2.0.0/ # release versions +├── 1.1.0/ +├── 1.0.0/ └── pr/ ├── 14/ # PR preview └── 13/ ``` -Shared logic is extracted into two composite actions: +## GitHub Actions workflows + +These workflows build, deploy, and clean up the documentation: -- **`.github/actions/build-docs`** -- Overrides `site_url` for the target subdirectory, builds the site, and stages the output -- **`.github/actions/deploy-to-gh-pages`** -- Checks out (or creates) the `gh-pages` branch and pushes the built site to a target subdirectory +| Workflow | Trigger | Deploys to | +| ----------------------- | ----------------- | --------------------------------------- | +| [`docs-dev.yml`] | Push to `main` | `/dev/`, `index.html` | +| [`docs-release.yml`] | Release | `//`, `/latest/`, `index.html` | +| [`docs-pr-preview.yml`] | PR opened/updated | `/pr//` | +| [`docs-pr-cleanup.yml`] | PR closed | removes `/pr//` | -A Python script (`.github/actions/build-docs/override_site_url.py`) uses [tomlkit](https://github.com/sdispater/tomlkit) to modify `site_url` in `zensical.toml` so that navigation and search work correctly in each subdirectory. +[`docs-dev.yml`]: .github/workflows/docs-dev.yml +[`docs-release.yml`]: .github/workflows/docs-release.yml +[`docs-pr-preview.yml`]: .github/workflows/docs-pr-preview.yml +[`docs-pr-cleanup.yml`]: .github/workflows/docs-pr-cleanup.yml -## Setup +The workflows require the GitHub settings -1. Install [uv](https://docs.astral.sh/uv/) -2. Build docs locally: - ``` - uv run --group docs zensical serve - ``` -3. Set GitHub Pages source to **Deploy from a branch** > `gh-pages` (root `/`) +- `Settings` > `Pages` > `Source` > `Deploy from a branch` > `gh-pages` (root `/`)