[branch-25.03] snap: fix build of embedded docs when building from source

docs/.wordlist.txt

@@ -14,6 +14,7 @@ JSON
 Juju
 Kubernetes
 Kubeflow
+MicroCloud
 MyST
 namespace
 namespaces

docs/Makefile

@@ -10,6 +10,7 @@ SOURCEDIR     = .
 BUILDDIR      = _build
 VENVDIR       = $(SPHINXDIR)/venv
 VENV          = $(VENVDIR)/bin/activate
+PIPOPTS       ?=
 
 
 # Put it first so that "make" without argument is like "make help".
@@ -25,8 +26,8 @@ $(SPHINXDIR)/requirements.txt:
 # If requirements are updated, venv should be rebuilt and timestamped.
 $(VENVDIR): $(SPHINXDIR)/requirements.txt
 	@echo "... setting up virtualenv"
-	python3 -m venv $(VENVDIR)
-	. $(VENV); pip install --require-virtualenv \
+	python3 -m venv --upgrade-deps $(VENVDIR)
+	. $(VENV); pip install $(PIPOPTS) --require-virtualenv \
         --upgrade -r $(SPHINXDIR)/requirements.txt \
         --log $(VENVDIR)/pip_install.log
 	@test ! -f $(VENVDIR)/pip_list.txt || \

docs/build-constraints.txt

@@ -0,0 +1,11 @@
+# Constrain indirect build dependencies.
+#
+# Note that any direct dependencies of packages mentioned in requirements.txt
+# must be constrained in `constraints.txt`.
+#
+# maturin v1.10 bumped Cargo.lock version to 4 which is not supported by rust
+# toolchain in a 24.04 build base.
+maturin==1.9.6
+
+# setuptools 82 drops the `pkg_resources` module.
+setuptools==81.0.0

docs/custom_conf.py

@@ -75,7 +75,7 @@
     # Change to the discourse instance you want to be able to link to
     # using the :discourse: metadata at the top of a file
     # (use an empty value if you don't want to link)
-    'discourse': 'https://discourse.ubuntu.com/c/microovn/support/164',
+    'discourse': 'https://discourse.ubuntu.com/c/project/microcloud/145',
 
     # Change to the GitHub URL for your project
     "github_url": "https://github.com/canonical/microovn",

docs/freeze-constraints.txt

@@ -0,0 +1,64 @@
+accessible-pygments==0.0.5
+alabaster==1.0.0
+anyio==4.12.0
+babel==2.17.0
+beautifulsoup4==4.14.3
+bracex==2.6
+canonical-sphinx-extensions==0.0.34
+certifi==2025.11.12
+charset-normalizer==3.4.4
+click==8.3.1
+colorama==0.4.6
+docutils==0.21.2
+furo==2025.9.25
+gitdb==4.0.12
+GitPython==3.1.45
+h11==0.16.0
+html5lib==1.1
+idna==3.11
+imagesize==1.4.1
+Jinja2==3.1.6
+linkify-it-py==2.0.3
+lxd-sphinx-extensions==0.0.16
+lxml==6.0.2
+Markdown==3.10
+markdown-it-py==3.0.0
+MarkupSafe==3.0.3
+mdit-py-plugins==0.5.0
+mdurl==0.1.2
+myst-parser==4.0.1
+packaging==25.0
+Pygments==2.19.2
+pyspelling==2.12.1
+PyYAML==6.0.3
+requests==2.32.5
+roman-numerals-py==3.1.0
+six==1.17.0
+smmap==5.0.2
+snowballstemmer==3.0.1
+soupsieve==2.8
+Sphinx==8.2.3
+sphinx-autobuild==2025.8.25
+sphinx-copybutton==0.5.2
+sphinx-notfound-page==1.1.0
+sphinx-reredirects==1.0.0
+sphinx-tabs==3.4.7
+sphinx_basic_ng==1.0.0b2
+sphinx_design==0.6.1
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0
+sphinxext-opengraph==0.13.0
+starlette==0.50.0
+typing_extensions==4.15.0
+uc-micro-py==1.0.3
+urllib3==2.5.0
+uvicorn==0.38.0
+watchfiles==1.0.5
+wcmatch==10.1
+webencodings==0.5.1
+websockets==15.0.1

docs/index.rst

@@ -59,7 +59,7 @@ constructive feedback.
 * Contribute to the project on `GitHub`_ (documentation contributions go under
   the :file:`docs` directory)
 * GitHub is also used as our bug tracker
-* To speak with us, you can find us in our `MicroOVN Discourse`_ category.
+* To speak with us, you can find us in our `MicroCloud Discourse`_ category.
 * Optionally enable `Ubuntu Pro`_ on your OVN nodes. This is a service that
   provides the `Livepatch Service`_ and the `Expanded Security Maintenance`_
   (ESM) program.
@@ -79,7 +79,7 @@ constructive feedback.
 .. _Open Virtual Network: https://www.ovn.org/en/
 .. _Code of conduct: https://ubuntu.com/community/ethos/code-of-conduct
 .. _GitHub: https://github.com/canonical/microovn
-.. _MicroOVN Discourse: https://discourse.ubuntu.com/c/microovn/160
+.. _MicroCloud Discourse: https://discourse.ubuntu.com/c/project/microcloud/145
 .. _Ubuntu Pro: https://ubuntu.com/pro
 .. _Livepatch Service: https://ubuntu.com/security/livepatch
 .. _Expanded Security Maintenance: https://ubuntu.com/security/esm

docs/readme.rst

@@ -134,3 +134,41 @@ the `woke User Guide <https://docs.getwoke.tech/usage/#file-globs>`_ for help).
 Some circumstances may compel you to retain some non-inclusive words. In such
 cases you will need to create check exemptions for them. See file
 :doc:`help-woke` for how to do that.
+
+Sphinx virtual environment Python dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For the purpose of consistent and reproducible builds, we freeze the direct
+and indirect Python dependencies of Sphinx.
+
+Change to specific dependencies can be accomplished by manually updating
+``docs/freeze-constraints.txt``.
+
+To refresh the whole set to most recent versions the following procedure can
+be used:
+
+1. Clear the current virtual environment and pip cache.
+
+.. code-block:: none
+
+   rm -rf .sphinx/venv
+   rm -rf ~/.cache/pip
+
+2. Build the virtual environment, overriding ``PIPOPTS`` to ensure build from
+   source without constraints.
+
+.. code-block:: none
+
+   make .sphinx/venv PIPOPTS="--no-binary :all:"
+
+.. note::
+
+   In the event of the current state of dependencies being in an impossible
+   state, populate the ``build-constraints.txt`` file and make use of the
+   ``--build-constraint`` argument in ``PIPOPTS``.
+
+3. Ensure everything works as expected and then record the new constraints.
+
+.. code-block:: none
+
+   .sphinx/venv/bin/pip freeze > freeze-constraints.txt

snap/snapcraft.yaml

@@ -377,7 +377,10 @@ parts:
       - cargo
     override-build: |
       set -ex
-      make .sphinx/venv || ( cat .sphinx/venv/pip_install.log && exit 1 )
+      make .sphinx/venv \
+          PIPOPTS="-c freeze-constraints.txt \
+                   --build-constraint build-constraints.txt" \
+          || ( cat .sphinx/venv/pip_install.log && exit 1 )
       make text
       rm -rf ${CRAFT_PART_INSTALL}/docs/microovn
       mkdir -p ${CRAFT_PART_INSTALL}/docs