docs: Build documentation to check for errors and add xcp.net class docs

.pre-commit-config.yaml

@@ -102,7 +102,7 @@ repos:
         name: pytest unit tests and static analysis using tox
         types: [python]
         # entry: sh -c "pytest -x -rf --new-first --show-capture=all >/dev/tty"
-        entry: sh -c "tox -e py311-cov-check-pytype-pyright-lint-mdreport >/dev/tty"
+        entry: sh -c "tox -e py311-cov-check-pytype-pyright-lint-docs-mdreport >/dev/tty"
         verbose: true
         language: python
         require_serial: true

docs/Makefile

@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -1,5 +1,6 @@
 six
 sphinx
 sphinx-autodoc-typehints
+sphinxcontrib-mermaid
 furo
 myst_parser

docs/source/accessor.rst

@@ -1,6 +1,11 @@
 xcp.accessor
 =============
 
+.. autoclasstree:: xcp.accessor
+   :title: Accessor class hierarchy
+   :caption: (class hierarchy automatically generated from xcp.accessor using Sphinx's autoclasstree directive)
+   :full:
+
 .. automodule:: xcp.accessor
     :members:
     :undoc-members:

docs/source/conf.py

@@ -3,6 +3,7 @@
 import logging
 import os
 import sys
+from datetime import datetime
 
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
@@ -30,19 +31,35 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "python-libs"
-copyright = "2025, Citrix Inc."
+copyright = "2025, Citrix Inc."  # pylint: disable=redefined-builtin
 author = "Citrix Inc."
-from datetime import datetime
-
 release = datetime.now().strftime("%Y.%m.%d-%H%M")
 
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html
+# Set the favicon and logo to XenServer branding.
+html_favicon = "https://xenserver.com/content/dam/xenserver/images/favicon-32x32.png"
+html_logo = "https://www.xenserver.com/content/dam/xenserver/images/xenserver-full-color-rgb.svg"
+
+# -- MyST-Parser configuration -----------------------------------------------
+# https://github.com/mgaitan/sphinxcontrib-mermaid:
+# Enables GitHub-style mermaid code blocks in markdown files.
+# See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+# This allows to use mermaid code blocks in markdown files like this:
+# ```mermaid
+#   graph TD;
+#     A-->B;
+# ```
+myst_fence_as_directive = ["mermaid"]
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
+    "sphinxcontrib.mermaid",
     "myst_parser",
 ]
 
@@ -55,4 +72,5 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
-html_static_path = ["_static"]
+# No static html source files for now.
+# html_static_path = ["_static"]

docs/source/index.rst

@@ -18,6 +18,11 @@ XenServer Python libs for Dom0
 .. image:: https://img.shields.io/badge/Sphinx-docs-blue.svg
    :target: https://python-libs.onrender.com/
 
+Welcome to the python-libs documentation!
+
+Each module is documented in its own section.
+Select a module from the menu to view its API documentation.
+
 .. toctree::
    :maxdepth: 2
    :caption: Project Documentation
@@ -46,7 +51,20 @@ XenServer Python libs for Dom0
    version
    xmlunwrap
 
-Welcome to the python-libs documentation!
+.. toctree::
+   :maxdepth: 2
+   :caption: XCP.Net Modules
+
+   net/biosdevname
+   net/ip
+   net/mac
 
-Each module is documented in its own section. Select a module from the menu to view its API documentation.
+.. toctree::
+   :maxdepth: 2
+   :caption: XCP.Net.Ifrename Modules
 
+   net/ifrename/ifrename-util
+   net/ifrename/ifrename-static
+   net/ifrename/ifrename-logic
+   net/ifrename/ifrename-dynamic
+   net/ifrename/ifrename-macpci

docs/source/net/biosdevname.rst

@@ -0,0 +1,7 @@
+xcp.net.biosdevname
+===================
+
+.. automodule:: xcp.net.biosdevname
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/net/ifrename/ifrename-dynamic.rst

@@ -0,0 +1,7 @@
+xcp.net.ifrename.dynamic
+========================
+
+.. automodule:: xcp.net.ifrename.dynamic
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/net/ifrename/ifrename-logic.rst

@@ -0,0 +1,7 @@
+xcp.net.ifrename.logic
+======================
+
+.. automodule:: xcp.net.ifrename.logic
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/net/ifrename/ifrename-macpci.rst

@@ -0,0 +1,7 @@
+xcp.net.ifrename.macpci
+=======================
+
+.. automodule:: xcp.net.ifrename.macpci
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/net/ifrename/ifrename-static.rst

@@ -0,0 +1,7 @@
+xcp.net.ifrename.static
+=======================
+
+.. automodule:: xcp.net.ifrename.static
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/net/ifrename/ifrename-util.rst

@@ -0,0 +1,7 @@
+xcp.net.ifrename.util
+=====================
+
+.. automodule:: xcp.net.ifrename.util
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/net/ip.rst

@@ -0,0 +1,7 @@
+xcp.net.ip
+==========
+
+.. automodule:: xcp.net.ip
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/net/mac.rst

@@ -0,0 +1,7 @@
+xcp.net.mac
+===========
+
+.. automodule:: xcp.net.mac
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/repository.rst

@@ -1,6 +1,11 @@
 xcp.repository
 ==============
 
+.. autoclasstree:: xcp.repository
+   :title: Repository class hierarchy
+   :caption: (class hierarchy automatically generated from xcp.repository using Sphinx's autoclasstree directive)
+   :full:
+
 .. automodule:: xcp.repository
     :members:
     :undoc-members:

tox.ini

@@ -12,7 +12,7 @@ min_version = 4.6
 # .github/workflows/main.yml is set up to test with 3.11, 3.12 and 3.13 in parallel.
 # Therefore, use three environments: One with 3.11, one with 3.12 and one with 3.13:
 #
-envlist = py311-covcp-check-pytype-mdreport, py312-cov, py313-cov-lint-pyright
+envlist = py311-covcp-check-pytype-mdreport, py312-cov-docs, py313-cov-lint-pyright
 isolated_build = true
 skip_missing_interpreters = true
 requires =
@@ -37,6 +37,7 @@ commands    =
 description = Run in a {basepython} virtualenv:
     cov:        {[cov]description}
     covcp:      Copy the generated .converage and coverage.xml to the UPLOAD_DIR dir
+    docs:       {[docs]description}
     fox:        {[fox]description}
     lint:       {[lint]description}
     mdreport:   Make a test report (which is shown in the GitHub Actions Summary Page)
@@ -56,12 +57,14 @@ deps =
     {cov,covcp,fox}: coverage[toml]
     {cov,covcp,fox}: diff-cover
     {lint,fox}: {[lint]deps}
+    docs: {[docs]deps}
     pyright: pyright
 allowlist_externals =
     {cov,covcp,fox,check,lint,test,mdreport}: echo
     {cov,covcp,fox,check,lint,test,mdreport}: sh
     {cov,covcp,fox}: cp
     check: cat
+    docs: make
     fox: firefox
 passenv =
     {pytype,lint,test}: GITHUB_STEP_SUMMARY
@@ -99,6 +102,7 @@ setenv =
     lint: ENVLOGDIR={envlogdir}
     {[cov]setenv}
 commands =
+    docs: {[docs]commands}
     lint: {[lint]commands}
     pyright: {[pyright]commands}
     check: {[check]commands}
@@ -126,6 +130,13 @@ commands    =
       --html-report  {envlogdir}/coverage-diff.html                                   \
                      {envlogdir}/coverage.xml
 
+
+[docs]
+description = Build the documentation to check for errors
+deps = -r docs/requirements.txt
+commands = make -C docs html SPHINXOPTS="--fail-on-warning"
+
+
 [lint]
 description = Run pylint and fail on warnings remaining on lines in the diff to master
 deps = pylint