Documentation site: guides and API reference on docs.tortal.tech/SavePoint #142

Merged
ethan-hann merged 6 commits from docs-site into main 2026-10-25 16:13:35 -05:00
Owner

Builds one static site from the guides in docs/ and an API reference generated from Savepoint.Core's doc comments, with DocFX as a local tool (docfx.json, docfx/). The site uses the app's look: the Material roles the app derives from the default Blue accent in light and dark, the app's Roboto files, and the app icon as logo and favicon.

.forgejo/workflows/docs.yml builds the site with warnings as errors on pull requests that touch its sources, and publishes it to the git-pages server at docs.tortal.tech under the path SavePoint on pushes to main that change those sources and on v* tags. The host is shared with other projects, so the workflow refuses an empty path. The upload is authorized by the workflow token and the _git-pages-forge-allowlist TXT record; the repository variable DOCS_SITE_URL is set.

The gate now treats docfx.json and docfx/ as documentation, so a change to the guides or the site alone takes the short path. The developer guide documents the site and the server setup, and D55 records the choice.

Builds one static site from the guides in docs/ and an API reference generated from Savepoint.Core's doc comments, with DocFX as a local tool (docfx.json, docfx/). The site uses the app's look: the Material roles the app derives from the default Blue accent in light and dark, the app's Roboto files, and the app icon as logo and favicon. .forgejo/workflows/docs.yml builds the site with warnings as errors on pull requests that touch its sources, and publishes it to the git-pages server at docs.tortal.tech under the path SavePoint on pushes to main that change those sources and on v* tags. The host is shared with other projects, so the workflow refuses an empty path. The upload is authorized by the workflow token and the _git-pages-forge-allowlist TXT record; the repository variable DOCS_SITE_URL is set. The gate now treats docfx.json and docfx/ as documentation, so a change to the guides or the site alone takes the short path. The developer guide documents the site and the server setup, and D55 records the choice.
DocFX (a local tool) builds the guides in docs/ and an API reference generated from Savepoint.Core into artifacts/docs-site. The site uses the app's look: the Material roles the app derives from the default Blue accent in light and dark, the app's Roboto files, and the app icon as logo and favicon.

.forgejo/workflows/docs.yml builds it with warnings as errors on pull requests that touch its sources, and on a v* tag uploads it to a git-pages server named by the repository variable DOCS_SITE_URL, authorized by the workflow token and a TXT record on the site's domain. The developer guide says how to run the server; D55 records the choice.
The git-pages host is shared with other projects, each under its own path, so the workflow uploads to the host's root with path SavePoint and refuses an empty path, which would replace every project. It also publishes on pushes to main that change the site's sources, so guide changes show without waiting for a release.
Treat the documentation site's sources as documentation in the gate
Some checks failed
Docs / site (pull_request) Successful in 2m8s
Gate / windows (pull_request) Has been cancelled
Gate / linux (pull_request) Has been cancelled
d1d4ac97de
docfx.json and docfx/ hold the site's configuration, home page and stylesheet, which no build or test reads, so a change to them alone takes the gate's short documentation path like docs/ does. docs.yml still builds the site for such a change, with warnings as errors.
Publish the docs as a project site of their own under the shared host
Some checks failed
Docs / site (pull_request) Successful in 2m5s
Gate / windows (pull_request) Has been cancelled
Gate / linux (pull_request) Has been cancelled
f5eea0d121
Patching a path into the host's root site needs a root site to exist and ties every project to it. A project site at <host>/SavePoint/ stands alone, so the host's index can live in a repository of its own.
The TXT-record method only admits a host's front page, so the server maps each path to the repository of the same name instead, and the front page to docs-index. The guide gives the config file and the extra mount, and D55 records why.
Retire the wiki mirror: the documentation site replaces it
All checks were successful
Docs / site (pull_request) Successful in 1m21s
Gate / linux (pull_request) Successful in 12m45s
Gate / windows (pull_request) Successful in 32m19s
Docs / site (push) Successful in 1m29s
Gate / linux (push) Successful in 12m56s
Gate / windows (push) Successful in 32m13s
87e1441699
The wiki workflow, build/wiki-sync.ps1 and its tests go; the forge's wiki link now points at docs.tortal.tech/SavePoint and its token was removed. The dogfood checklist, which lived only on the wiki, is docs/dogfood-checklist.md and on the site, with its install and uninstall checks updated for the moved data folder. The README points at the site.
Sign in to join this conversation.
No reviewers
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
ethan-hann/SavePoint!142
No description provided.