docs: replace previous docs with sphinx docs

.github/workflows/ci.yaml

@@ -60,7 +60,7 @@ jobs:
               - 'src/**/go.mod'
               - 'src/**/go.sum'
             docs:
-              - 'rtd-docs/**'
+              - 'docs/**'
 
   lint:
     runs-on: ubuntu-24.04
@@ -131,16 +131,16 @@ jobs:
       with:
         fetch-depth: 0
     - name: Create venv
-      working-directory: "rtd-docs"
+      working-directory: "docs"
       run: make install
     - name: Lint markdown
-      working-directory: "rtd-docs"
+      working-directory: "docs"
       run: make lint-md
     - name: Test build
-      working-directory: "rtd-docs"
+      working-directory: "docs"
       run: make html
     - name: Run scripts tests
-      working-directory: "rtd-docs"
+      working-directory: "docs"
       run: |
         source .sphinx/venv/bin/activate
         pip install -r requirements-dev.txt

.readthedocs.yaml

@@ -18,15 +18,15 @@ build:
     # This is a special exit code on Read the Docs that will cancel the build immediately.
     # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
     - |
-      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- 'rtd-docs/' '.readthedocs.yaml';
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- 'docs/' '.readthedocs.yaml';
       then
         exit 183;
       fi
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: dirhtml
-  configuration: rtd-docs/conf.py
+  configuration: docs/conf.py
   fail_on_warning: true
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
@@ -36,4 +36,4 @@ formats:
 # Optionally declare the Python requirements required to build your docs
 python:
   install:
-  - requirements: rtd-docs/requirements.txt
+  - requirements: docs/requirements.txt

Makefile

@@ -60,8 +60,6 @@ endef
 
 UI_BUILD := src/maasui/build
 
-OFFLINE_DOCS := src/maas-offline-docs/src
-
 swagger-dist := src/maasserver/templates/dist/
 swagger-js: file := src/maasserver/templates/dist/swagger-ui-bundle.js
 swagger-js: url := "https://unpkg.com/swagger-ui-dist@latest/swagger-ui-bundle.js"
@@ -125,9 +123,6 @@ ui: $(UI_BUILD)
 $(UI_BUILD):
 	$(MAKE) --no-print-directory -C src/maasui build
 
-$(OFFLINE_DOCS):
-	$(MAKE) --no-print-directory -C src/maas-offline-docs
-
 $(swagger-dist):
 	mkdir $@
 

debian/control

@@ -8,15 +8,20 @@ Build-Depends: clang,
                dh-exec,
                dh-python,
                fakeroot,
+               git,
                golang-go (>= 2:1.24~),
                libbpf-dev,
+               libcairo2-dev,
                libdqlite1.17-dev,
                llvm,
                po-debconf,
                python3-all,
+               python3-dev,
                python3-django,
+               python3-pip,
                python3-setuptools,
-               python3-twisted
+               python3-twisted,
+               python3-venv
 Standards-Version: 4.1.3
 X-Python3-Version: >= 3.14
 Homepage: http://maas.io/

debian/rules

@@ -30,7 +30,11 @@ override_dh_auto_install:
 	# Collect static files
 	install -d -m 755  $(CURDIR)/debian/tmp/usr/share/maas/web/
 	mv $(CURDIR)/src/maasui/build $(CURDIR)/debian/tmp/usr/share/maas/web/static
-	make -C $(CURDIR)/src/maas-offline-docs install DESTDIR=$(CURDIR)/debian/tmp BUILD_TYPE=deb
+
+	# Build and install offline docs
+	make -C $(CURDIR)/docs html
+	install -d -m 755 $(CURDIR)/debian/tmp/usr/share/maas/web/static/docs
+	cp -a $(CURDIR)/docs/_build/. $(CURDIR)/debian/tmp/usr/share/maas/web/static/docs/
 
 	# Build resources binaries
 	make -C $(CURDIR)/src/host-info install DESTDIR=$(CURDIR)/debian/tmp

rtd-docs/_scripts/generate_api_docs.py → docs/_scripts/generate_api_docs.py

@@ -8,7 +8,7 @@
 and converting it to Markdown suitable for inclusion in the RTD documentation.
 
 Usage:
-    python3 rtd-docs/_scripts/generate_api_docs.py
+    python3 docs/_scripts/generate_api_docs.py
 """
 
 from collections import defaultdict
@@ -150,18 +150,26 @@ def prepare_template_data(spec: dict[str, Any]) -> dict[str, Any]:
             # Format parameters
             formatted_params = []
             for param in all_params:
-                formatted_params.append(format_parameter(param, endpoint_params))
+                formatted_params.append(
+                    format_parameter(param, endpoint_params)
+                )
 
             # Format request body
             formatted_request_body = []
             if "requestBody" in operation:
-                formatted_request_body = format_request_body(operation["requestBody"])
+                formatted_request_body = format_request_body(
+                    operation["requestBody"]
+                )
 
             # Format responses
             formatted_responses = []
             if "responses" in operation:
-                for status_code, response in sorted(operation["responses"].items()):
-                    formatted_responses.append(format_response(status_code, response))
+                for status_code, response in sorted(
+                    operation["responses"].items()
+                ):
+                    formatted_responses.append(
+                        format_response(status_code, response)
+                    )
 
             endpoint_data = {
                 "path": path,

rtd-docs/_scripts/utils.py → docs/_scripts/utils.py

@@ -15,17 +15,12 @@ def add_repo_src_to_path():
     Assumes the root of the repo is being tracked by git, and that it
     is the first parent that is so.
     """
-    project_root = next(
-        (
-            parent
-            for parent in Path(__file__).parents
-            if (parent / ".git").exists()
-        ),
-        None,
+    project_root = (
+        Path(__file__).parents[2] if len(Path(__file__).parents) >= 3 else None
     )
     if project_root is None:
         raise Exception(
-            "root of the project was not found... is your MAAS repo not being tracked by git?"
+            "root of the project was not found... check the path tree for docs scripts"
         )
 
     src_dir = project_root / "src"

rtd-docs/conf.py → docs/conf.py

@@ -1,13 +1,54 @@
 import datetime
+import importlib
 import os
 from pathlib import Path
 import sys
+import warnings
 
 import yaml
 
 # Add custom extensions directory to Python path
 sys.path.insert(0, str(Path(__file__).parent / "_ext"))
 
+from types import ModuleType
+
+extensions = []
+
+if (
+    len(Path(__file__).parents) >= 2
+    and not (Path(__file__).parents[1] / ".git").exists()
+):
+    # Some surgery in order to accomodate the fact that
+    # canonical_sphinx and sphinx_sitemap both require
+    # sphinx_last_updated_by_git in a way that is not possible
+    # to circumvent externally.
+    mock_git_ext = ModuleType("sphinx_last_updated_by_git")
+    mock_git_ext.__path__ = []
+    mock_git_ext.__file__ = "mock_sphinx_last_updated_by_git.py"
+    mock_git_ext.__spec__ = importlib.machinery.ModuleSpec(
+        name="sphinx_last_updated_by_git", loader=None, origin="mock"
+    )
+
+    def dummy_setup(app):
+        app.connect(
+            "env-updated",
+            lambda _, env: setattr(env, "git_last_updated", {}),
+        )
+        return {"version": "0.1", "parallel_read_safe": True}
+
+    mock_git_ext.setup = dummy_setup
+
+    sys.modules["sphinx_last_updated_by_git"] = mock_git_ext
+else:
+    extensions.append("sphinx_last_updated_by_git")
+
+
+# Suppress the specific warning message from sphinx_sitemap
+warnings.filterwarnings(
+    "ignore",
+    message=".*sphinx_last_updated_by_git.*",
+)
+
 # Configuration for the Sphinx documentation builder.
 # All configuration specific to your project should be done in this file.
 #
@@ -146,7 +187,7 @@
     # Docs location in the repo; used in links for viewing the source files
     #
     # TODO: To customise the directory, uncomment and update as needed.
-    "repo_folder": "/rtd-docs/",
+    "repo_folder": "/docs/",
     # TODO: To enable or disable the Previous / Next buttons at the bottom of pages
     # Valid options: none, prev, next, both
     # "sequential_nav": "both",
@@ -282,7 +323,7 @@
 
 # NOTE: The canonical_sphinx extension is required for the starter pack.
 
-extensions = [
+extensions += [
     "generate_api_docs_extension",  # Auto-generate API docs during build
     "generate_cli_docs_extension",  # Auto-generate CLI docs during build
     "canonical_sphinx",
@@ -301,11 +342,11 @@
     "sphinx_ubuntu_images",
     "sphinx_youtube_links",
     "sphinxcontrib.cairosvgconverter",
-    "sphinx_last_updated_by_git",
     "sphinx.ext.intersphinx",
     "sphinx_sitemap",
 ]
 
+
 # Prevents MyST-Parser from flagging strikethrough as a non-portable feature.
 # Since Docutils lacks a universal 'strike' node, this warning persists for
 # non-HTML formats. Safe to ignore for Read the Docs web builds.