Skip to content

docs: Ship the MkDocs documentation site with the installation#7747

Open
petrasovaa wants to merge 1 commit into
OSGeo:mainfrom
petrasovaa:ship-mkdocs-installation
Open

docs: Ship the MkDocs documentation site with the installation#7747
petrasovaa wants to merge 1 commit into
OSGeo:mainfrom
petrasovaa:ship-mkdocs-installation

Conversation

@petrasovaa

Copy link
Copy Markdown
Contributor

Part of the transition to markdown-based documentation.

TL;DR:
make install/make bindist and cmake --install now build and ship the MkDocs documentation site, which g.manual and the GUI then use; if mkdocs is 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:

  • Autotools: make install and make bindist build the site into the dist tree via a new top-level build-mkdocs target; the install copy then includes it.
  • CMake: an install(CODE) step runs mkdocs build during cmake --install.

When mkdocs is not on PATH at install time (e.g. it is in a user environment but the install runs under sudo), a site built beforehand (make -C man build-mkdocs or the build-mkdocs CMake 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_NAME with the site published by the documentation workflow: the title is now
GRASS <major>.<minor> Documentation everywhere, while the exact version (including dev) 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).

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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CMake docs markdown Related to markdown, markdown files

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

1 participant