docs: Add Sphinx autodoc generation

Signed-off-by: Bernhard Kaindl <[email protected]>

Author: bernhardkaindl

.readthedocs.yml

@@ -0,0 +1,23 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally, set the documentation type
+# formats:
+#   - html
+#   - pdf
+#   - epub

CONTRIBUTING.md

@@ -202,7 +202,7 @@ For more information to debug `pytest` test suites see
 ## Running GitHub actions locally using `act`
 
 With `docker` (or `podman`) installed, [act](https://github.com/nektos/act) can be used to run
-the CI jobs configured in [.actrc](.actrc):
+the CI jobs configured in [`.actrc`](https://github.com/xenserver/python-libs/blob/master/.actrc):
 
 - `act` uses `docker` (also mimicked by `podman-docker`) to run GitHub actions locally
 - While `act` does not use the same GitHub runner images, they are similar.

DOCUMENTING.md

@@ -0,0 +1,57 @@
+# Documenting using Sphinx
+
+This project uses **Google style docstrings** for Python code documentation. These docstrings are compatible with Sphinx (with the `sphinx.ext.napoleon` extension) and other documentation tools.
+
+## Why Google Style Docstrings?
+
+- Clear, readable format
+- Widely supported by documentation generators
+- Easy to maintain
+
+## Example Google Style Docstring
+
+```python
+def add(a: int, b: int) -> int:
+    """Add two integers.
+
+    Args:
+        a (int): First integer.
+        b (int): Second integer.
+
+    Returns:
+        int: The sum of `a` and `b`.
+
+    Raises:
+        ValueError: If either argument is not an integer.
+    """
+    if not isinstance(a, int) or not isinstance(b, int):
+        raise ValueError("Arguments must be integers.")
+    return a + b
+```
+
+## Steps to Document Your Code
+
+1. **Write Google style docstrings** for all public modules, classes, and functions.
+2. **Include sections** such as `Args`, `Returns`, `Raises`, and `Examples` as needed.
+3. **Keep docstrings concise and informative.**
+
+## Benefits of using Sphinx
+
+- Supports docstring formats – such as Google-style, NumPy-style, and reST.
+- Autodoc extension – can automatically extract documentation from Python docstrings.
+- Integration with Read the Docs – makes it easy to publish and host documentation online.
+- Theme support – like Read the Docs theme or the modern Furo theme.
+
+## Building the documentation
+
+```bash
+pip install -r docs/requirements.txt
+make -C docs html
+```
+
+Open `docs/html/index.html` in a web browser.
+
+## References
+
+- [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
+- [Sphinx Napoleon Documentation](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+sphinx-autodoc-typehints
+furo
+myst_parser

docs/source/accessor.rst

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

docs/source/bootloader.rst

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

docs/source/cmd.rst

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

docs/source/compat.rst

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

docs/source/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+# -- Path setup -------------------------------------------------------------
+import logging
+import os
+import sys
+
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# Add project root to sys.path for autodoc to find xcp modules and it allows
+# to {include} the toplevel README.md files from their wrapper files here.
+sys.path.insert(0, os.path.abspath("../.."))
+
+# Add stubs directory to sys.path for stubs (xcp/bootloader.py needs a branding.py)
+sys.path.insert(0, os.path.abspath("../../stubs"))
+
+#
+# To support Markdown-based documentation, Sphinx can use MyST-Parser.
+# MyST-Parser is a Docutils bridge to markdown-it-py, a Python package
+# for parsing the CommonMark Markdown flavor.
+# See https://myst-parser.readthedocs.io/en/latest/ for details.
+# Set the log level of markdown-it log categories to INFO to disable DEBUG
+# logging and prevent flooding the logs with many 1000s of DEBUG messages:
+#
+logging.getLogger("markdown_it.rules_block").setLevel(logging.INFO)
+logging.getLogger("markdown_it.rules_inline").setLevel(logging.INFO)
+logging.getLogger("markdown_it").setLevel(logging.INFO)
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "python-libs"
+copyright = "2025, Citrix Inc."
+author = "Citrix Inc."
+from datetime import datetime
+
+release = datetime.now().strftime("%Y.%m.%d-%H%M")
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "myst_parser",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]