Skip to content

docs: add per-module pages, README table, and small src cleanup#21

Merged
github-actions[bot] merged 5 commits into
developfrom
docs/content-review
May 19, 2026
Merged

docs: add per-module pages, README table, and small src cleanup#21
github-actions[bot] merged 5 commits into
developfrom
docs/content-review

Conversation

@nolte
Copy link
Copy Markdown
Owner

@nolte nolte commented May 18, 2026

Summary

Expand the documentation surface for the reusable Taskfile includes: replace
the flat README bullet list with a module table, add per-module pages under
docs/modules/, wire them into the mkdocs navigation, and fix two small
correctness issues in the k8s and mkdocs source includes.

Changes

  • Replace the bullet list in README.md with a table that lists each module's
    tasks and key tunable variables.
  • Add per-module documentation pages under docs/modules/ for mkdocs, kind,
    pre-commit, and k8s, each with a Tasks / Variables / Example layout.
  • Add a nav: section to mkdocs.yml exposing an Overview plus a Modules
    group, so the new pages are reachable from the rendered site.
  • Fix kubectl create namespace argocd | true|| true in
    src/taskfile-include-k8s.yaml so a pre-existing namespace no longer aborts
    the bootstrap.
  • Normalise indentation under bootstrap.cmds in the same file.
  • Drop the stray YAML document marker (---) at the top of
    src/taskfile-include-mkdocs.yaml.

Linked issues

None

Testing

  • pre-commit run --all-files — all hooks pass (check-yaml, end-of-file-fixer,
    trailing-whitespace).
  • Manually reviewed the rendered diff of README.md and the new docs/modules/
    pages.

Risk / rollout notes

Low risk. Documentation-only on the consumer-visible surface; the two src/
changes are bug fixes (| true|| true makes re-runs idempotent; removing
the stray --- has no semantic effect on Taskfile parsing).

- docs/modules/{mkdocs,kind,pre-commit,k8s}.md: task/variable tables per module with override examples
- mkdocs.yml: nav with Overview + Modules group
- README.md: replace intro bullet list with Module/Tasks/Variables table
- src/taskfile-include-k8s.yaml: `| true` -> `|| true` on kubectl create namespace; align cmds indentation
- src/taskfile-include-mkdocs.yaml: drop stray `---` doc separator for consistency

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rephrase four Vale suggestions surfaced by Microsoft.Passive,
Microsoft.ComplexWords, and Microsoft.Vocab:

- pre-commit module page: "against every file" → "over every file"
- PR template: "being added" → "you are adding"
- bug/feature/PR templates: "prioritize" → "rank"

Repo-level errors and remaining suggestions on H1 identifiers
(taskfiles, k8s, kind, pre-commit) are upstream-vocab candidates
for nolte/vale-style and intentionally left in place. Title-cased
section headings in .github/ templates follow the HashiCorp
issue-template convention and are also left as-is.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@boring-cyborg boring-cyborg Bot added the chore Maintenance label May 18, 2026
Audit against spec/project/project-structure/ surfaced seven items:

- Add release-publish.yml (mandatory per branching-model spec) pinned
  to nolte/gh-plumbing@v1.1.12, on: workflow_dispatch only.
- Pin automerge.yaml and spelling.yaml from @develop to @v1.1.12 so
  release-pipeline behaviour stays reproducible (AC §135).
- Expose `task lint` and `task docs` wrappers in Taskfile.yml (SHOULD
  per spec §CI and automation). No `test` target — repo ships YAML
  includes only, no runtime code.
- Scaffold spec/ and tests/ with .gitkeep stubs.
- Add MIT LICENSE.

Open: tests/ stays empty per spec Open Question §7 (YAML-only repo
without runtime code); GitHub-App installation could not be verified
automatically because the local token lacks the required scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@boring-cyborg boring-cyborg Bot added cicd ci/cd process functionality. spec labels May 19, 2026
nolte and others added 2 commits May 19, 2026 16:56
Stop the three reviewdog annotations on PR #21 (Microsoft.Headings on
k8s, kind, pre-commit) and the two repo-wide Vale.Spelling errors on
"taskfiles" by accepting them through a local vocabulary:

- .github/styles/config/vocabularies/taskfiles/accept.txt with k8s,
  kind, pre-commit, taskfiles
- .vale.ini: Vocab = taskfiles
- .gitignore: allow .github/styles/config/ to be tracked while keeping
  the rest of the synced styles excluded

Result: vale --no-exit . goes from 2 errors + 19 suggestions to
0 errors + 14 suggestions; the remaining suggestions are HashiCorp-
style Title Case headings in .github/ templates and the "are
interested" community-note footer, both intentionally untouched.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous exception (`!.github/styles/config/**`) was too broad and
would have started tracking vendored Vale vocabularies once they show
up under .github/styles/config/vocabularies/ — for example the
`technical` set that `vale sync` pulls from nolte-styles. Restrict the
exception to .github/styles/config/vocabularies/taskfiles/ so only the
repo-local vocab is tracked.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@nolte nolte marked this pull request as ready for review May 19, 2026 15:17
@nolte nolte added the automerge Allow automatic Merge. label May 19, 2026
@github-actions github-actions Bot merged commit f398b46 into develop May 19, 2026
8 checks passed
@github-actions github-actions Bot deleted the docs/content-review branch May 19, 2026 15:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automerge Allow automatic Merge. chore Maintenance cicd ci/cd process functionality. documentation spec

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant