Skip to content

chore: add prepare-docs / build-docs, and run them in CI - #265

Merged
Naruto merged 1 commit into
developfrom
chore/docs-build-scripts
Aug 11, 2026
Merged

chore: add prepare-docs / build-docs, and run them in CI#265
Naruto merged 1 commit into
developfrom
chore/docs-build-scripts

Conversation

@Naruto

@Naruto Naruto commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Adds the documentation build pair every repository in the family now shares, and points pages.yml at it.

scripts/prepare-docs.sh / .ps1 .venv + the pins in docs/requirements.txt
scripts/build-docs.sh / .ps1 English then Japanese, both --strict

Both take key=value options and --help, like the other scripts in scripts/:
prepare-docs.sh python=py force=yes, build-docs.sh locale=ja venv=.venv.

Why the -docs suffix

prepare and build are names the code build wants in several of these repositories, so the documentation pair carries -docs and is the same four names everywhere. SpriteStudio-Docs renamed its own pair to match.

What build-docs gets right

  • Locale order. The English build clears site/, and the Japanese site lives inside it at site/ja — so English first, Japanese second. The opposite order publishes a site with no Japanese pages at all. locale=en on its own warns that it just deleted site/ja.
  • --strict, always. Nothing builds the docs on a pull request, so a local run is the only gate there is.

CI

pages.yml calls the two scripts instead of repeating pip install -r + two zensical build lines. With no PR build there is nothing to catch CI and the README drifting apart, so the build is now spelled out in one place. build-docs.sh falls back to zensical on PATH when there is no venv, so the old shape would still have worked — running prepare-docs.sh keeps CI on exactly what a contributor runs.

Validation

prepare-docs.sh then build-docs.sh — both locales, --strict, No issues found. The .ps1 twins were run under pwsh, a bad option exits 2, and the locale=en warning fires. Nothing builds the docs on a PR, so that local run is the gate.

Every repository in the family now spells the documentation build the same way,
and the -docs suffix keeps the pair apart from the scripts that build the code
itself:

  scripts/prepare-docs.sh|.ps1   .venv + the pins in docs/requirements.txt
  scripts/build-docs.sh|.ps1     English then Japanese, both --strict

Both take key=value options and --help, like the other scripts here. build-docs
owns the locale order -- the English build clears site/ and the Japanese site
lives inside it at site/ja, so the opposite order publishes a site with no
Japanese pages at all -- and it always passes --strict.

pages.yml now calls those two scripts rather than repeating the commands. With
no PR build there is nothing to catch CI and the README drifting apart, so the
build is spelled out in one place. build-docs.sh falls back to zensical on PATH
when there is no venv, so the previous `pip install -r` shape would still work;
running prepare-docs.sh keeps CI on exactly what a contributor runs.

Verified locally: both locales build --strict, and the .ps1 twins run under pwsh.
@Naruto
Naruto merged commit dbedf80 into develop Aug 11, 2026
0 of 2 checks passed
@Naruto
Naruto deleted the chore/docs-build-scripts branch August 11, 2026 11:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant