chore: add prepare-docs / build-docs, and run them in CI - #265
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the documentation build pair every repository in the family now shares, and points
pages.ymlat it.scripts/prepare-docs.sh/.ps1.venv+ the pins indocs/requirements.txtscripts/build-docs.sh/.ps1--strictBoth take
key=valueoptions and--help, like the other scripts inscripts/:prepare-docs.sh python=py force=yes,build-docs.sh locale=ja venv=.venv.Why the
-docssuffixprepareandbuildare names the code build wants in several of these repositories, so the documentation pair carries-docsand is the same four names everywhere. SpriteStudio-Docs renamed its own pair to match.What
build-docsgets rightsite/, and the Japanese site lives inside it atsite/ja— so English first, Japanese second. The opposite order publishes a site with no Japanese pages at all.locale=enon its own warns that it just deletedsite/ja.--strict, always. Nothing builds the docs on a pull request, so a local run is the only gate there is.CI
pages.ymlcalls the two scripts instead of repeatingpip install -r+ twozensical buildlines. 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.shfalls back tozensicalonPATHwhen there is no venv, so the old shape would still have worked — runningprepare-docs.shkeeps CI on exactly what a contributor runs.Validation
prepare-docs.shthenbuild-docs.sh— both locales,--strict,No issues found. The.ps1twins were run underpwsh, a bad option exits 2, and thelocale=enwarning fires. Nothing builds the docs on a PR, so that local run is the gate.