bernhard-xapi · bernhardkaindl · Sep 22, 2025 · Sep 2, 2025 · Sep 2, 2025 · Sep 26, 2025
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -25,6 +25,19 @@ env:
   PIP_DISABLE_PIP_VERSION_CHECK: "1" # Reduce noise in logs
 
 jobs:
+  pre-commit:
+    env:
+      SKIP: pytest,pytype,tox,no-commit-to-branch
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v5
+    - uses: actions/setup-python@v6
+      with:
+        python-version: 3.11
+    - uses: pre-commit/[email protected]
+    - uses: pre-commit-ci/[email protected]
+      if: always()
+
   test:
     strategy:
       # See: https://github.com/xenserver/python-libs/pull/26#discussion_r1179482169
@@ -43,13 +56,13 @@ jobs:
     env:
       PYTHON_VERSION_USED_FOR_COVERAGE: ${{ '3.11' }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0  # Needed by diff-cover to get the changed lines: origin/master..HEAD
       - name: Set up Python ${{ matrix.python-version }}
         # Python 3.11 is not supported in the nektos/act container, so we skip this step
         if: ${{ !(matrix.python-version == '3.11' && github.actor == 'nektos/act') }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

diff --git a/.pre-commit-config.yaml b/.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
@@ -115,6 +115,7 @@ repos:
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
+        exclude: docs/source/index.rst
     -   id: check-yaml
     -   id: check-added-large-files
         args: ['--maxkb=50']

diff --git a/README-Unicode.md b/README-Unicode.md
@@ -4,20 +4,20 @@
 
 Python3.6 on XS8 does not have an all-encompassing default UTF-8 mode for I/O.
 
-Newer Python versions have an UTF-8 mode that they even enable by default.
-Python3.6 only enabled UTF-8 for I/O when an UTF-8 locale is used.
+Newer Python versions have a UTF-8 mode that they even enable by default.
+Python3.6 only enabled UTF-8 for I/O when a UTF-8 locale is used.
 See below for more background info on the UTF-8 mode.
 
 For situations where UTF-8 enabled, we have to specify UTF-8 explicitly.
 
-Such sitation happens when LANG or LC_* variables are not set for UTF-8.
-XAPI plugins like auto-cert-kit find themself in this situation.
+This happens when LANG or LC_* variables are not set for UTF-8.
+XAPI plugins like auto-cert-kit find themselves in this situation.
 
 Example:
 For reading UTF-8 files like the `pciids` file, add `encoding="utf-8"`.
-This applies especailly to `open()` and `Popen()` when files my contain UTF-8.
+This applies especially to `open()` and `Popen()` when files may contain UTF-8.
 
-This also applies when en/decoding to/form `urllib` which uses bytes.
+This also applies when en/decoding to/from `urllib` which uses bytes.
 `urllib` has to use bytes as HTTP data can of course also be binary, e.g. compressed.
 
 ## Migrating `subprocess.Popen()`
@@ -132,19 +132,9 @@ To fix these issues, `xcp.compat`, provides a wrapper for `open()`.
 It adds `encoding="utf-8", errors="replace"`
 to enable UTF-8 conversion and handle encoding errors:
 
-    ```py
-    # xcp/utf8mode.py
-    if sys.version_info >= (3, 0):
-        def utf8open(*args, **kwargs):
-            if len(args) > 1 and "b" in args[1]:
-                return open(*args, **kwargs)
-            return open(*args, encoding="utf-8", errors="replace", **kwargs)
-    else:
-        utf8open = open
-    # xcp/{cmd,pci,environ?,logger?}.py tests/test_{pci,biodevname?,...?}.py
-    + from .utf8mode import utf8open
-    ...
-    - open(filename)
-    + utf8open(filename)
-    ```
-
+```py
+    def utf8open(*args, **kwargs):
+        if len(args) > 1 and "b" in args[1]:
+            return open(*args, **kwargs)
+        return open(*args, encoding="utf-8", errors="replace", **kwargs)
+```
diff --git a/docs/Makefile b/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)
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,6 @@
 six
 sphinx
 sphinx-autodoc-typehints
+sphinxcontrib-mermaid
 furo
 myst_parser
diff --git a/docs/source/accessor.rst b/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:

diff --git a/docs/source/conf.py b/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"]
diff --git a/docs/source/include-toplevel-CONTRIBUTING.md b/docs/source/include-toplevel-CONTRIBUTING.md
@@ -1,2 +1,2 @@
 ```{include} ../../CONTRIBUTING.md
-:parser: myst
+:parser: myst
diff --git a/docs/source/include-toplevel-DOCUMENTING.md b/docs/source/include-toplevel-DOCUMENTING.md
@@ -1,2 +1,2 @@
 ```{include} ../../DOCUMENTING.md
-:parser: myst
+:parser: myst
diff --git a/docs/source/include-toplevel-README-Unicode.md b/docs/source/include-toplevel-README-Unicode.md
@@ -1,2 +1,2 @@
 ```{include} ../../README-Unicode.md
-:parser: myst
+:parser: myst
diff --git a/docs/source/include-toplevel-README.md b/docs/source/include-toplevel-README.md
@@ -1,2 +1,2 @@
 ```{include} ../../README.md
-:parser: myst
+:parser: myst
diff --git a/docs/source/index.rst b/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
diff --git a/docs/source/net/biosdevname.rst b/docs/source/net/biosdevname.rst
@@ -0,0 +1,7 @@
+xcp.net.biosdevname
+===================
+
+.. automodule:: xcp.net.biosdevname
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/net/ifrename/ifrename-dynamic.rst b/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:
diff --git a/docs/source/net/ifrename/ifrename-logic.rst b/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:
diff --git a/docs/source/net/ifrename/ifrename-macpci.rst b/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:
diff --git a/docs/source/net/ifrename/ifrename-static.rst b/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:
diff --git a/docs/source/net/ifrename/ifrename-util.rst b/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:
diff --git a/docs/source/net/ip.rst b/docs/source/net/ip.rst
@@ -0,0 +1,7 @@
+xcp.net.ip
+==========
+
+.. automodule:: xcp.net.ip
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/net/mac.rst b/docs/source/net/mac.rst
@@ -0,0 +1,7 @@
+xcp.net.mac
+===========
+
+.. automodule:: xcp.net.mac
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/repository.rst b/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: