docs: publish enhancement proposals on the documentation site - #701
docs: publish enhancement proposals on the documentation site#701ArangoGutierrez wants to merge 2 commits into
Conversation
MkDocs builds only what lives under docs_dir, so the MEPs in enhancements/ were reachable from the site only as links out to GitHub. Moving them under docs/ would contradict the workflow in enhancements/README.md, which tells contributors to add proposals under enhancements/meps/, and would break every link already pointing there. The build takes a copy instead: hack/sync-enhancement-docs.sh stages enhancements/ into docs/enhancements/ ahead of every mkdocs run, from docs-build, docs-serve and docs-check-exclusion alike. The copy is gitignored and its destination is deleted on each run, so a renamed or removed MEP cannot linger in a later build. MEP text is written to render on GitHub, and MEP-0002 links three levels up into pkg/ and tests/. Those targets do not exist inside docs_dir and mkdocs --strict rejects them, so the copy step rewrites them to GitHub blob URLs and then checks that the rewrite landed, which a silently non-matching sed would otherwise surface much later as an opaque strict-mode failure. The originals keep their relative form and stay correct on GitHub. deploy-pages.yaml filters on paths, so a MEP-only change would have matched nothing and never reached the site. enhancements/** and the sync script join the filter; the build command itself is unchanged. Closes NVIDIA#698 Signed-off-by: Carlos Eduardo Arango Gutierrez <eduardoa@nvidia.com>
|
|
||
| name: Deploy documentation to Pages | ||
|
|
||
| # The MEPs are published from enhancements/, which `make docs` stages into the |
There was a problem hiding this comment.
The comment is redundant for long-term readers, it's the agent trying to document what it's done for the specific task/chat.
There was a problem hiding this comment.
Fair, that was narrating the change rather than the code. Trimmed it to the part a later reader actually needs, which is that enhancements/ sits outside docs_dir so the filter only works because make docs stages it. Pushed as e78ad8b.
| paths: | ||
| - "docs/**" | ||
| - "enhancements/**" | ||
| - "hack/sync-enhancement-docs.sh" |
There was a problem hiding this comment.
I know ppl create these hack dirs but it's not it better to name it "tools"? 😃
There was a problem hiding this comment.
I'd keep hack/ here. hack/golang-version.sh is already in there and both variables.yaml and nvml-mock-e2e-go.yaml call it, and there's no tools/ yet, so renaming just this one would leave us with two script directories. Happy to move both in a separate change if you'd rather standardise on tools/.
| - fake-gpu-operator: integrations/fake-gpu-operator.md | ||
| # These pages are a build-time copy of enhancements/ staged by | ||
| # hack/sync-enhancement-docs.sh; docs/enhancements/ is gitignored. Adding a MEP | ||
| # means adding it to enhancements/meps/ and listing it here. |
There was a problem hiding this comment.
Would this be easier to move enhancements under docs? I feel like it may save us this back-and-forth with coding docs. We can make it a requirement to register new MEPs in this table of content.
There was a problem hiding this comment.
Your instinct about the cost is right, though I think the script buys less than it looks like it does.
Registration is manual either way. The nav above lists every MEP by hand, and moving the directory would not remove that step, so the sync is not saving us the back-and-forth you are thinking of. What it actually buys is only that MEPs stay at enhancements/, next to the README that documents the process and where someone browsing the repo expects to find them. The price is the script plus the Makefile wiring and two path filters.
Keeping it on that basis for now, but it is a close call and I will move it if you would rather have the ~120 fewer lines. The thing that would flip me is wanting MEPs to use the rest of the docs tooling, snippets and cross-page links, since that is markedly simpler inside docs_dir.
The comment narrated the change rather than the code. What a later reader needs is the dependency itself: enhancements/ is outside docs_dir, so the filters only work because make docs stages it. Signed-off-by: Carlos Eduardo Arango Gutierrez <eduardoa@nvidia.com>
2 participants
Closes #698.
enhancements/meps/holds two proposals with architecture diagrams that wereonly reachable as links out to GitHub, because MkDocs publishes nothing outside
docs_dir.Rather than move them,
hack/sync-enhancement-docs.shstages them into thedocs tree at build time. That keeps the MEP process where contributors expect
it: a new MEP lands in
enhancements/as it always has and appears on the sitewith no second location to remember. The staged copy is gitignored and rebuilt
from scratch each run, so a stale copy cannot survive.
Every target that runs mkdocs depends on the sync, so
make docs,make docs-serveand the exclusion guard all see the same tree, and CI needs nospecial-casing.
One deviation from the issue as filed:
deploy-pages.yamldoes change. Its pathfilters had to learn about
enhancements/**and the sync script, becausewithout that a MEP edit would not rebuild the site and the published copy would
drift from the source.
docs/helm-chart.mdpreviously linked MEP-0002 by absolute GitHub URL; it nowpoints at the in-site page.
make docspasses, and the MEP images are emitted into the built site ratherthan only the pages that reference them.