diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt index 8e1d7628..d37887d7 100644 --- a/docs/.wordlist.txt +++ b/docs/.wordlist.txt @@ -14,6 +14,7 @@ JSON Juju Kubernetes Kubeflow +MicroCloud MyST namespace namespaces diff --git a/docs/Makefile b/docs/Makefile index 5f7c0386..e797ca35 100644 --- a/docs/Makefile +++ b/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 || \ diff --git a/docs/build-constraints.txt b/docs/build-constraints.txt new file mode 100644 index 00000000..d9beddb7 --- /dev/null +++ b/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 diff --git a/docs/custom_conf.py b/docs/custom_conf.py index 38e9ace2..18c2e5ba 100644 --- a/docs/custom_conf.py +++ b/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", diff --git a/docs/freeze-constraints.txt b/docs/freeze-constraints.txt new file mode 100644 index 00000000..101a8348 --- /dev/null +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index 27b3207a..ec1dd55b 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/readme.rst b/docs/readme.rst index fd885ee0..5673d235 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -134,3 +134,41 @@ the `woke User Guide `_ 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 diff --git a/snap/snapcraft.yaml b/snap/snapcraft.yaml index b9374b6b..2c2a0219 100644 --- a/snap/snapcraft.yaml +++ b/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