Publishing the website
The website is the same documentation as the editor's Help, built for the web by one command. The download lives in a separate bucket and is uploaded by a script that checks every byte. Nothing here is uploaded automatically.
The web build
The web build starts from the same pages as Docs/Site/out and leaves that folder alone. It then:
- links Download for Windows on the home page and the download block of Download and install straight to the zip on the download host, with its size, SHA-256 (with a copy button), release date and release notes;
- serves pretty addresses (
/manual/installinstead of/manual/install.html), as the website host does; - adds a canonical address, a description and social share tags with the KROYS share image to every page, and the favicon set;
- adds
?v=<hash>to every stylesheet, script, font and image reference, so they can be cached for a year while a new deployment is visible at once; - writes
sitemap.xml,robots.txt, a404.htmlin the site's style and a_headersfile with security headers and cache rules; - checks every internal link, anchor and asset, allows outside links only to the site and the release files, keeps the host's limits (fewer than 20,000 files, none over 25 MiB) and fails when a local path or a user name would be published.
The offline build (no --publish) is unchanged: it makes no outside links or requests and works from a file on disk.
PowerShell
python Tools/BuildDocsSite.py --publish # writes Dist/publish/site python Tools/BuildDocsSite.py --publish --out D:\site --dist D:\release
Release values
Docs/Site/site.json holds the site address, the download address, the bucket name and the file names. The version comes from Config/EngineVersion.json and the release date from CHANGELOG.md. The size and SHA-256 are read from the zip in --dist (default Dist); its .sha256 file must match the zip, or the build stops. Without the zip, the release entry in site.json must pin the same version with its size and SHA-256.
The release notes page is generated from CHANGELOG.md, one section per release, newest first; it is in the offline Help too.
Upload a release
The script uploads KroysEngine-<version>-win64.zip, its .sha256 and release-notes-<version>.md from Dist/publish/downloads/releases/<version> (or Dist) to releases/<version>/ in the download bucket, over the S3-compatible API with signed requests. Large files go up in 64 MiB parts, each signed with its own SHA-256, so a damaged part is refused. Afterwards it checks each object's size and stored SHA-256, and that the .sha256 in the bucket names the zip's hash; --full-verify downloads the zip again and hashes it.
The access key comes from the environment (KROYS_R2_ACCOUNT_ID, KROYS_R2_ACCESS_KEY_ID, KROYS_R2_SECRET_ACCESS_KEY) or a prompt. It is never written to a file or printed; use a token limited to the download bucket and delete it when you are done.
python Tools/TestUploadRelease.py runs the uploader against a mock server on 127.0.0.1 that checks the signature, the payload hashes and the multipart flow. It contacts nothing else.PowerShell
python Tools/UploadRelease.py --dry-run # what would go where; no network python Tools/UploadRelease.py # upload and check python Tools/UploadRelease.py --verify-only --full-verify
Images
python Tools/MakeSiteImages.py renders the share image (1200×630, the KROYS wordmark split on the mirror axis) and the favicons from Docs/Site/src/icon.svg with a headless browser into Docs/Site/src/brand. The images are committed; run it again only when the wordmark or the colours change.
Who publishes
Building and uploading are separate from publishing: a person uploads the site folder to the website host and runs the upload script with their own token, following the publishing guide written next to the build output.
KroysEngine 0.1.0 documentation, built from the engine repository by Tools/BuildDocsSite.py.