docs(build): unified output subtree under docs/build/#4081
Open
grandixximo wants to merge 2 commits into
Open
Conversation
All rendered artefacts (HTML, PDF, po4a-translated .adoc) move under
docs/build/. Layout:
docs/build/html/index.html static redirect -> en/
docs/build/html/{shared assets, CSS}
docs/build/html/<lang>/index.html
docs/build/html/<lang>/<topic>/<page>.html
docs/build/html/<lang>/man/manN/<page>.html
docs/build/html/<lang>/pdf/LinuxCNC_*[_<lang>].pdf
docs/build/adoc/<lang>/ po4a-translated source
English now has its own en/ subdir so every language is symmetric
and the top-level redirect lands users on the right tree.
Manpage troff stays at docs/man/ (halcompile output, install-man /
mandb / rip-environment read it).
Static assets in the former output dir docs/html/ go to docs/src/
(gcode.html, index.css, logo); asciidoc-py-era leftovers are dropped.
debian/*.docs and po4a.cfg are repointed at the new tree. Install
destinations under usr/share/doc/ are unchanged.
Also moves three build-time artefacts that previously leaked into
docs/src/ to the new build tree, so the source tree stays clean and
no per-build .gitignore entries are needed:
docs/src/man/man1/linuxcnc.1.adoc (config.status output)
-> docs/build/adoc/en/man/man1/linuxcnc.1.adoc
The manpage HTML rule grows a build-tree fallback so the
English manpage build still finds it; the explicit troff rule
is duplicated from the generic pattern (sources under
docs/src/man/) since the build-tree path no longer matches.
docs/src/drivers/mb2hal_HOWTO.ini (.include-stamp copy)
-> docs/build/adoc/en/drivers/mb2hal_HOWTO.ini
mb2hal.adoc's include now uses {fixturedir}, set per-language
by the asciidoctor HTML rule. The link: target still copies
to docs/build/html/<lang>/drivers/ for runtime download.
po files repointed at the new include path.
docs/src/gui/gmoccapy_release_notes.txt (.include-stamp copy)
Dead code under the new layout: gmoccapy.adoc only link:s the
file (HTML render time), and the recipe already copies it
next to the rendered HTML.
Contributor
Author
Contributor
Author
|
reverting to draft till it builds on sid |
…ionally CI on PR LinuxCNC#4081 failed for two reasons exposed by --enable-build-documentation=pdf: * The asciidoctor PDF rule did not set the fixturedir attribute, so the mb2hal {fixturedir}/drivers/mb2hal_HOWTO.ini include resolved literally in every Master_Documentation*.pdf and asciidoctor reported it missing. Pass fixturedir=$(DOC_OUT_ADOC)/<lang> from the rule, where <lang> is the literal "en" for the English call site and $(firstword $(subst /, ,$*)) for the per-language call site (so the same recipe serves both). * docs/build/html/en/gcode.html only got copied as a side effect of .copy-asciidoc-stamp, which lives under htmldocs. debian/configure sets --enable-build-documentation=pdf for CI, so htmldocs never fires and the en/ copy never lands, breaking dh_installdocs --package= linuxcnc-doc-en. Promote the copy to its own rule, depended on unconditionally by `docs:`.
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
1 participant
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
Move all rendered docs artefacts (HTML, PDF, po4a-translated
.adoc) under a singledocs/build/tree, drop asciidoc-py-era leftovers indocs/html/, and stop leaking build-time artefacts intodocs/src/.Builds on top of #4053 (asciidoctor migration). Implements Bertho's layout proposal agreed in the #4053 discussion.
Layout
English now lives under
en/like every other language, so the top-level redirect lands users on the right tree.Manpage troff stays at
docs/man/because halcompile output,install-man,mandb, andrip-environmentread it.Source-tree cleanup
Three build-time artefacts no longer leak into
docs/src/:docs/src/man/man1/linuxcnc.1.adoc(config.status output)docs/build/adoc/en/man/man1/linuxcnc.1.adocdocs/src/drivers/mb2hal_HOWTO.ini(include fixture)docs/build/adoc/en/drivers/mb2hal_HOWTO.inidocs/src/gui/gmoccapy_release_notes.txtmb2hal.adoc'sinclude::now uses the{fixturedir}attribute, set per-language by the asciidoctor HTML rule. The 8.pofiles are repointed at the new include path (mechanical msgid edit, no po4a regen).The manpage HTML rule grows a build-tree fallback so the English manpage build finds
linuxcnc.1.adoc; theLinuxCNC_Manual_Pages.pdfmaster generator grows the same fallback. An explicit troff rule forlinuxcnc.1replaces the generic pattern (which expects sources underdocs/src/man/).Static assets in the former output dir
docs/html/move todocs/src/(gcode.html,index.css, logo). asciidoc-py-era files (asciidoc.css,linuxcnc.css,minus.png,plus.png) are deleted.debian/*.docsanddocs/po4a.cfgare repointed at the new tree. Install destinations underusr/share/doc/are unchanged.Test plan
cd src && make -j$(nproc)clean full buildmb2hal.htmlcontains the example INI fixture in all 8 languagesLinuxCNC_Documentation.pdfcontains the mb2hal INI fixturelinuxcnc(1)troff renders todocs/man/man1/linuxcnc.1linuxcnc(1)HTML and PDF (inLinuxCNC_Manual_Pages.pdf) both contain the manpage bodymake doccleanleaves no generated.adoc/.ini/.txtindocs/src/git clean -dxn docs/src/reports onlyhal/components_gen.adoc(pre-existing, generated bygen_complist.py, not from this PR)