The hub of https://dev-guides.home/: the estate's guides for agents, one site per guide under its
own path, with an index page and a root llms.txt over them. This repo holds the hub, the checker
every guide is held to, and the one Jenkins pipeline that builds and publishes them all. The
guides themselves live in the source repos on sources.txt, this one included.
The guide contract (what a guide folder holds, its site_url, its nav, its llms.txt, its rule
anchors) is the dev-guides skill in the kubecoder plugin. This README describes the repo, not
the contract.
tools/check_guide.py <repo-dir>builds every guide in a source repo with the guide's own toolchain and checks it against the contract. It is every source repo'skc project test.tools/build_hub.py [<root>...]builds the site intoout/: it runs the checker over every repo onsources.txt, each from the first root that holds it, copies each guide'ssite/toout/<path>/, and writes the index page and the rootllms.txt. It is the one definition of the site's layout; theDockerfileand this repo'skc project testboth run it.sources.txtnames the source repos, side by side under one directory: the Jenkins workspace afterCheckout. A pod holds some of them in/work, and the rest in/work/scratch.landing/is the index page's template and its favicon.build_hub.pywrites one card per guide into it, from the guide'ssite_nameandsite_description.tools/fetch_sources.pyclones the source repos a pod carries no checkout of into/work/scratch, or fast-forwards the clones there tomain.kc project setup,testandbuildrun it.tools/stage_context.pycopies the source repos' working trees, without what git ignores, into the image's build context forkc project build.Dockerfileandnginx.confmake theregistry:5000/dev-guides-homeimage: a Python stage that runsbuild_hub.py, then nginx servingout/.Jenkinsfileis the jobDevGuides.
Public guides can live here too, as top-level folders like any source repo's.
kc project testbuilds the whole hub over the source repos' working trees: those under/work, and for the rest themainclones under/work/scratch. Every guide is built and checked, then the index and the rootllms.txtassembled and their links checked. It is green only when every source repo's guides are.kc project buildstages the context under/work/scratch/dev-guides-contextand builds the image withkaniko --no-push, as the job builds it.kc project lintruns Ruff overtools/, the rules and the formatting, with the settingsruff.tomlpins. The job does not run it.
The job DevGuides clones this repo and every other repo on sources.txt in Checkout, builds
the image (the checks run inside the image build, so a failing guide never ships), and pins it
into pvginkel/DevGuidesDeploy at images.devGuides. Argo CD deploys it from there.
The clones in Checkout are also the triggers: a push to any repo the job's last build checked out
starts the job, so the source repos have no job of their own. One guide's failure blocks the
publish of all of them.
Every other source repo runs this repo's checker from its raw URL, so there is one copy:
uv run https://raw.githubusercontent.com/pvginkel/DevGuides/main/tools/check_guide.py <repo-dir>
A change to the checker changes every repo's gate once it is on main. Before then, run it from
this tree: uv run /work/DevGuides/tools/check_guide.py <repo-dir>.
A new guide in an existing source repo needs nothing here. A new source repo takes two edits in the same commit:
- its name in
sources.txt; - its clone in the
Jenkinsfile'sCheckoutstage, adir('<Repo>') { git … }beside the others.
build_hub.py fails when a repo on sources.txt was not cloned.