Repository navigation
docs: move the manual to MkDocs Material (#501) - #505
Merged
Merged
Conversation
CommandsNav and WriteNav build the MkDocs nav for the Commands section from the cobra tree and write it as docs/site/commands-nav.json. GenMarkdownTree and the navigation share one visible() rule, so the pages and the entries cannot drift. gen-docs takes the pages directory and the navigation file, and .gitignore covers the new generated paths. Refs #501
Pinned to the tip of feature/4b-copia-cli-docs (d79086b); the MkDocs site uses its theme through custom_dir. Refs #501
…theme Add mkdocs.yml with the theme from the brand submodule, a hook that puts the generated command navigation under Commands, hash-pinned requirements, stub pages for the hand-written navigation (Task 6 fills them) and the docs, docs-serve, docs-build and docs-clean recipes. Refs #501
go test ./test/docs/ generates the manual and its navigation into a temporary directory and checks that the generated pages link only to each other, that the navigation lists each of them once, and that they carry no Jekyll markup. It also checks that the hand-written site pages link only to command pages that exist, that the copia-cli lines in their shell blocks name real commands, and that every page in mkdocs.yml's nav exists. Refs #501
The Linux, macOS, Windows and source guides move to docs/site/docs/install/ with every heading kept, so the anchors the README links to still exist. GitHub note blocks become admonitions, and the Go version of the source build now matches go.mod. The overview page lists every method per platform. The old files point to the site, and docs/README.md says where the user documentation lives. Refs #501
The site's authentication page covers creating a token, auth login, the keyring and its config-file fallback, COPIA_TOKEN with COPIA_HOST, several accounts and auth switch, auth status, auth setup-git and the precedence (#auth-precedence). docs/authentication.md links to it and keeps the developer details; its Auth Precedence heading points to the user page. Refs #501
cobra's Find stops at a command group such as issue and returns the unknown word as an argument, so copia-cli issue lst passed the guard. A line now fails when the command it resolves to does not run and words are left over, which catches a subcommand that was renamed or removed. Refs #501
config.DefaultPath uses $XDG_CONFIG_HOME/copia/config.yml when that is set, and ~/.config/copia/config.yml otherwise, on macOS and Windows too; both pages now say so. auth switch picks from the accounts that match its flags, or all of them: one match is switched to, of two the one not in use, and only when it cannot decide does it fail with the list. Refs #501
The manual is now built with MkDocs Material and the Qubernetic docs theme instead of Jekyll. The build job checks out this repository without a key and without submodules, reads the pinned brand commit from the gitlink, and fetches qubernetic/brand at that SHA into docs/site/brand in a second checkout with BRAND_DEPLOY_KEY: with an ssh-key, actions/checkout would fetch this repository with that key too, and the brand deploy key is not valid for it. MkDocs Material is installed from the hash-pinned docs/site/requirements.txt and the site is built with --strict. Pushes to main deploy as before; a manual dispatch from another branch uploads the build as the artifact docs-site and does not deploy. The trigger paths now cover the generator and the submodule pin. Refs #501
Six tests keep docs.yml off pull requests, deploy it from main only, keep the brand deploy key in the one checkout that fetches the theme, require a strict build, keep MkDocs Material pinned by hash at the theme's version and make the trigger paths cover the generator. Refs #501
The README links the installation guides on the site and says how the site is built and what a local build needs. CLAUDE.md and CONTRIBUTING.md describe docs.yml and the site layout, the changelog records the move, and docs/project-layout.md no longer names Jekyll. Refs #501
The docs workflow shared one concurrency group, "pages", with
cancel-in-progress, so a rehearsal dispatched from a branch cancelled a
main run that was building or deploying, and the live site stayed on
the old version without a report. The group is now
pages-${{ github.ref }}: a newer run still cancels an older one on the
same ref, but two refs never share a group. A test keeps github.ref in
the group.
Refs #501
CLAUDE.md lists what test/workflows enforces in docs.yml instead of claiming all of it, and both CLAUDE.md and CONTRIBUTING.md describe the per-ref concurrency group. CONTRIBUTING.md no longer says the install matches copr's: both are hash-pinned, but docs needs neither --no-build-isolation nor apt's setuptools and wheel. The project layout says which manual pages are generated. Refs #501
Break the Example lines that ran past the 66-character column of the generated manual at a flag with a backslash, and split long comment lines in two. Behaviour, flags and help text are unchanged. Refs #501
Shorten the pr create example on the home page and in the quick start: the head is the current branch and the base defaults to main. Shorten the setup-git comment in the authentication guide. Refs #501
printFlags escaped the usage text and appended the default afterwards, so a default such as <none> would vanish from the page as an HTML tag. The usage and the default are now escaped together. Refs #501
The link checks saw inline links only, so a reference definition such as [x]: ../manual/copia-cli_gone.md passed go test and failed only the strict site build. They now read reference definitions too. escapeAngles knows only backtick fences and code spans within one line. A new check classifies the lines of each generated page the way MkDocs reads them and fails on "<" in a fenced or indented code block or in a code span, also one a line break splits. Definition continuation lines, which printFlags indents by four spaces, are prose, not code. Refs #501
pkg/cmdutil defines the text of shared flags shown on the command pages (--json, --jq, --template), and a cobra or pflag bump in go.mod and go.sum can change the pages too. Add the three to push.paths of docs.yml and to TestDocsPathsCoverTheGenerator. Refs #501
The secret checks counted the literal "secrets.", so secrets['X'] or
toJSON(secrets) in another step slipped by; they now match the secrets
context as a word. TestDocsBuildIsStrict was a substring match that
passed with "|| true" or continue-on-error; the build step must now run
the one mkdocs command and neither the step nor the build job may set
continue-on-error. The concurrency group must be exactly
pages-${{ github.ref }}, not any group that contains github.ref.
Refs #501
pr create defaults the head to the current branch only with --web or --fill; with --title alone it sends an empty head. Home and the quick start now show copia-cli pr create --fill and say what --fill takes from the commits, and Home links to the releases page. Refs #501
curl does not expand *, so the latest/download URLs of the .deb and .rpm returned 404. The package names hold the version (.goreleaser.yml sets no nfpm file name template, so goreleaser's default copia-cli_<version>_linux_<arch> applies), and no stable latest/download name exists. The page now sends the reader to the latest release and shows the install command with a <version> placeholder. Refs #501
just docs-build and docs-serve resolved mkdocs-material==9.7.6 and its dependencies freely, while CI installs the hashed set of docs/site/requirements.txt. Both recipes now run uv run --with-requirements requirements.txt from docs/site, so a local strict build uses the versions CI uses. Refs #501
The docs/site/brand submodule pointed at cf6e122 on the brand repository's feature branch. That branch is now merged, so the pin moves to the merge commit 7f030a6 on develop, the commit the brand remote will serve to CI. The theme files are unchanged between the two commits. Refs #501
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
# Conflicts: # CHANGELOG.md # CLAUDE.md # docs/site/_includes/sidebar.html
Fetch qubernetic/brand over HTTPS and set update = none, so git clone --recursive and a bare git submodule update --init no longer fail without access to the private theme. The site build fetches it with git submodule update --init --checkout docs/site/brand.
The ubuntu-24.04 runner already has pip3, so the apt-get update only made the deploy on main depend on the apt mirrors.
The extensionless Jekyll addresses redirect to the new pages, the .html ones do not. Link the completion page with its trailing slash.
Merged
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.
Summary
Moves the manual from Jekyll to MkDocs Material with the Qubernetic docs theme. The theme is the private submodule
docs/site/brand(qubernetic/brand), pinned to itsdevelopmerge commit7f030a6. The installation guides move to the site as well, anddocs.ymlnow builds the site withmkdocs build --strict.Closes #501
Changes
docs/site/: the MkDocs project (mkdocs.yml,requirements.in, hashedrequirements.txt,hooks/commands_nav.py) and the hand-written pages (home, getting started,install/linux|macos|windows|source).internal/docs,script/gen-docs.go: the generator writes MkDocs pages for the 88 commands andcommands-nav.json, which the hook splices into the navigation..github/workflows/docs.yml: runs on pushes tomainand on manual dispatch.buildgenerates the pages, fetches the theme with the read-only deploy keyBRAND_DEPLOY_KEYin a checkout of its own, installs withpip3 install --require-hashes, and builds strict. Pages upload anddeployrun frommainonly. A dispatch from another branch uploads the build as the artifactdocs-site.test/workflows/docs_test.go: six tests pin those rules (triggers, main-only deploy, the key in exactly one step, strict build, hashed requirements withmkdocs-material==9.7.6, the path filter).justfile:docs-buildanddocs-servebuild from the pinned requirements, so a local build uses the versions CI uses.README.md,CLAUDE.md,CONTRIBUTING.md,CHANGELOG.md,docs/project-layout.md,docs/install_*.md: describe the new site and link to it.Packaging does not fetch the submodule
Checked file by file, because the submodule is private and a release must not need it:
release.yml,snap.yml,copr.yml,aur.yml,ci.yml: no checkout setssubmodules:, and no step runsgit submodule..goreleaser.yml: nobefore:hooks. It builds./cmd/copia-cli, which imports nothing underdocs/site. An uninitialised gitlink leavesgit status --porcelainempty, so the dirty-tree check is not tripped.snap/snapcraft.yaml:plugin: gowithsource: .;override-buildruns onlygit describeandgo build.rpmbuild/copia-cli.spec:Source0/Source1are the release tarballs, so no git is involved.grep -i submoduleover.github/,.goreleaser.yml,snap/,rpmbuild/,justfileandscript/finds only the comment indocs.yml.--recurse-submoduleshad a cleangit statusand an emptydocs/site/brand.Rehearsal
gh workflow run docs.yml --ref feature/501-docs-mkdocs-material: https://github.com/qubernetic/copia-cli/actions/runs/43863565328buildsucceeded,deploywas skipped, and the artifactdocs-sitewas uploaded.Automated checks
go test ./...andgolangci-lint run ./...were green at8625926; the only commit since,b3ba857, moves the submodule pinmkdocs build --strictpasses locally atb3ba857docs.ymlrehearsal above passes atb3ba857Test plan
/copia-cli/manual/,/copia-cli/manual/copia-cli_completion,/copia-cli/manual/copia-cli_pr_create.https://docs.twincatmcp.qubernetic.comanswers.copia-cli pr create --fill) reads correctly; it changed after the checkpoint review.Notes for reviewer
docs.ymlhas two checkouts on purpose: the repository without credentials, then the theme with the key.test/workflowsfails if they are merged.BRAND_DEPLOY_KEYis a repository secret.builddeclares no environment, so an environment secret would be empty there.just docsdo not need it.apicommand page the list of field rules runs together into one paragraph. The fix is in the command'sLongtext underpkg/cmd.ac26b23andb537820are imprecise. The branch is pushed, so they stay as they are.