From d330484e364ed46f21d630db23665bf1d73eb561 Mon Sep 17 00:00:00 2001 From: Elijah Greenstein Date: Wed, 5 Aug 2026 15:54:15 -0700 Subject: [PATCH] doc: add checks on docs integration The docs integration often depends on overwriting files in the upstream LXD, MicroCeph, and MicroOVN repositories. If those files move or if configuration settings change, it is possible for the build to complete successfully, but with incorrect settings or other issues. This commit separates the `integrate` process in the docs Makefile into several steps: - `integrate-pull` clones the upstream repositories and pins them to specific commits - `integrate-precheck` (depends on `integrate-pull`) confirms that various files are located where expected, and are configured as expected - `integrate` (depends on `integrate-precheck`) copies and overwrites files, and builds the documentation Signed-off-by: Elijah Greenstein --- doc/Makefile | 69 +++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 66 insertions(+), 3 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 7ec7516c1..270d06f95 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -47,7 +47,8 @@ help: vale pa11y run serve install pa11y-install \ vale-install clean clean-doc lint-md lint \ integrate clean-integrate html html-rtd microcloud \ - serve-microcloud pymarkdownlnt-install + serve-microcloud pymarkdownlnt-install \ + integrate-pull integrate-precheck full-help: $(DOCS_VENVDIR) @. $(DOCS_VENV); $(SPHINX_BUILD) -M help "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(O) @@ -81,7 +82,7 @@ install: $(DOCS_VENVDIR) run: install . $(DOCS_VENV); $(DOCS_VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) -integrate: +integrate-pull: # Pull the other repositories cd integration/ && ( git -C lxd fetch || git clone https://github.com/canonical/lxd ) git -C integration/lxd reset --hard $(LXDVERSION) @@ -92,10 +93,72 @@ integrate: cd integration/ && ( git -C microovn fetch || git clone https://github.com/canonical/microovn ) git -C integration/microovn reset --hard $(MICROOVNVERSION) +# Integration prechecks +# +# - Header templates: Check that header.html files exist in expected locations. +# If these files are missing, then the upstream repo may have reorganized the +# templates. The integrate rule will copy the integrated docs header, but that +# header may not end up being used in the built documentation. +# - Configuration files: Check that `conf.py` files exist in expected locations. +# If the configuration files are missing, then they may have been moved, and +# appending `add_conf.py` with `>>` may create new `conf.py` files that will +# not be used by the upstream configuration. +# - MicroOVN tag: The integrated docs use the circle of friends logo by +# overwriting the MicroOVN logo. Check that the MicroOVN logo is located where +# expected. +# - SEO noindex tags: +# - LXD: verify upstream `base.html`, with `seo_noindex` check and `noindex` +# tag +# - MicroCeph: verify that there is no `base.html` file in the upstream docs +# - MicroOVN: verify upstream base.html file, that extends furo and does not +# already have an extrahead block +integrate-precheck: integrate-pull + @echo "Running integration prechecks ..." + + @echo "Checking for template files ..." + @test -f integration/lxd/doc/_templates/header.html || \ + { echo "ERROR: LXD header.html template not found. Update the integration."; exit 1; } + @test -f integration/microceph/docs/_templates/header.html || \ + { echo "ERROR: MicroCeph header.html template not found. Update the integration."; exit 1; } + @test -f integration/microovn/docs/.sphinx/_templates/header.html || \ + { echo "ERROR: MicroOVN header.html template not found. Update the integration."; exit 1; } + + @echo "Checking for configuration files ..." + @test -f integration/lxd/doc/conf.py || \ + { echo "ERROR: LXD conf.py not found. Update the integration."; exit 1; } + @test -f integration/microceph/docs/conf.py || \ + { echo "ERROR: MicroCeph conf.py not found. Update the integration."; exit 1; } + @test -f integration/microovn/docs/conf.py || \ + { echo "ERROR: MicroOVN conf.py not found. Update the integration."; exit 1; } + + @echo "Checking for MicroOVN tag ..." + @test -f integration/microovn/docs/.sphinx/_static/microovn.png || \ + { echo "ERROR: MicroOVN tag not found. Update the integration."; exit 1; } + + @echo "Checking noindex tag setup ..." + @echo "- Checking LXD noindex setup..." + @test -f integration/lxd/doc/_templates/base.html || \ + { echo "ERROR: No base.html file in LXD docs. Update the noindex integration."; exit 1; } + @grep -q 'seo_noindex' integration/lxd/doc/_templates/base.html || \ + { echo "ERROR: LXD's base.html does not check seo_noindex. Update the noindex integration."; exit 1; } + @grep -q 'content="noindex"' integration/lxd/doc/_templates/base.html || \ + { echo "ERROR: LXD's base.html does not contain the noindex tag. Update the noindex integration."; exit 1; } + @echo "- Checking MicroCeph noindex setup..." + @test ! -f integration/microceph/docs/_templates/base.html || \ + { echo "ERROR: MicroCeph docs now include base.html. Update the noindex integration."; exit 1; } + @echo "- Checking MicroOVN noindex setup..." + @test -f integration/microovn/docs/.sphinx/_templates/base.html || \ + { echo "ERROR: No base.html file in MicroOVN docs. Update the noindex integration."; exit 1; } + @grep -q 'extends "furo/base.html"' integration/microovn/docs/.sphinx/_templates/base.html || \ + { echo "ERROR: MicroOVN base.html no longer extends furo/base.html. Update the noindex integration."; exit 1; } + @! grep -q 'extrahead' integration/microovn/docs/.sphinx/_templates/base.html || \ + { echo "ERROR: MicroOVN base.html defines extrahead block. Update the noindex integration."; exit 1; } + +integrate: integrate-precheck # Create a directory for files to override in MicroCloud docs mkdir -p integration/microcloud/_templates/ integration/microcloud/_static mkdir -p integration/microceph/docs/_templates integration/microceph/docs/_static - + # Copy the header HTML, CSS files, and Google Tag Manager for the doc sets cp .sphinx/_integration/microcloud.html integration/microcloud/_templates/header.html cp _templates/google-tag.html integration/microcloud/_templates/