docs: Ship the MkDocs documentation site with the installation#7747
Open
petrasovaa wants to merge 1 commit into
Open
docs: Ship the MkDocs documentation site with the installation#7747petrasovaa wants to merge 1 commit into
petrasovaa wants to merge 1 commit into
Conversation
Build the site at install and bindist time in both build systems so mkdocs does not become a dependency of the default build. When mkdocs is missing at install time, install a previously built site if there is one, otherwise skip the site with a warning; g.manual and the GUI then keep using their fallbacks. Implemented with AI assistance (Claude Fable).
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.
Part of the transition to markdown-based documentation.
TL;DR:
make install/make bindistandcmake --installnow build and ship the MkDocs documentation site, which g.manual and the GUI then use; ifmkdocsis missing, the site is skipped with a warning and nothing else changes.Ship the MkDocs documentation site with the installation. g.manual and the GUI help viewer already prefer $GISBASE/docs/mkdocs/site` when it exists, so installs pick it up automatically; the legacy HTML pages remain as fallback until a later phase removes them.
The site is built at install time rather than in the default build, so
mkdocs(man/mkdocs/requirements.txt) does not become a build dependency and CI is unaffected:make installandmake bindistbuild the site into the dist tree via a new top-levelbuild-mkdocstarget; the install copy then includes it.install(CODE)step runsmkdocs buildduringcmake --install.When
mkdocsis not onPATHat install time (e.g. it is in a user environment but the install runs undersudo), a site built beforehand (make -C man build-mkdocsor thebuild-mkdocsCMake target) is still installed; without one, the site is skipped with a warning. A failed build likewise warns instead of aborting the install.Also align the local targets'
SITE_NAMEwith the site published by the documentation workflow: the title is nowGRASS <major>.<minor> Documentationeverywhere, while the exact version (includingdev) stays in the copyright footer.Note for packagers: the site adds roughly 120-200 MB, temporarily double accounting next to the legacy HTML pages until those are removed.
Implemented with AI assistance (Claude Fable).