docs: publish libvirt-python API docs via GitLab pages

Add jobs:
 - website_job
 - pages
to build libvirt-python API docs using Sphinx.

Created base on libvirt-php/libvirt-java/libvirt-ruby examples.

Signed-off-by: Radoslaw Smigielski <rsmigiel@redhat.com>

Author: radeksm

.gitlab-ci.yml

@@ -3,6 +3,7 @@ stages:
   - containers
   - builds
   - sanity_checks
+  - pages
 
 .git_build_vars: &git_build_vars |
   export MAKEFLAGS="-j$(getconf _NPROCESSORS_ONLN)"
@@ -57,6 +58,49 @@ stages:
 
 include: '/ci/gitlab.yml'
 
+# Build Sphinx HTML API docs.
+py_api_docs:
+  extends:
+    - .gitlab_native_build_job
+  needs:
+    - job: x86_64-fedora-44-container
+      optional: true
+  script:
+    - export MAKEFLAGS="-j$(getconf _NPROCESSORS_ONLN)"
+    - export CFLAGS="-Werror"
+    - $PYTHON -m build -n -x
+    - $PYTHON -m venv docs-venv --system-site-packages --symlinks
+    - docs-venv/bin/python -m pip install dist/libvirt_python*.whl
+    - docs-venv/bin/python -m pip install -r requirements-docs.txt
+    - docs-venv/bin/sphinx-build -b html docs/ py_api_docs
+  artifacts:
+    expose_as: 'py_api_docs'
+    name: 'py_api_docs'
+    when: on_success
+    expire_in: 30 days
+    paths:
+      - py_api_docs
+  variables:
+    NAME: fedora-44
+    TARGET_BASE_IMAGE: registry.fedoraproject.org/fedora:44
+
+# Publish "py_api_docs" output via GitLab Pages
+pages:
+  stage: pages
+  script:
+    - mv py_api_docs public
+  dependencies:
+    - py_api_docs
+  rules:
+    - if: '$CI_PROJECT_NAMESPACE == $RUN_UPSTREAM_NAMESPACE && $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+      when: on_success
+    - when: never
+  artifacts:
+    expose_as: 'pages'
+    name: 'pages'
+    paths:
+      - public
+
 api_coverage_job:
   extends:
     - .gitlab_native_build_job

docs/conf.py

@@ -28,6 +28,41 @@
 
 html_theme = 'alabaster'
 html_theme_options = {
-    'description': 'Python bindings for the libvirt virtualization API',
+    'description': 'Python bindings for the libvirt API',
     'github_button': False,
 }
+
+
+def _needs_literal_docstring(lines):
+    """Here comes a little bit of magic.
+    This function returns True if docstring content is unsafe as reStructuredText,
+    it will tell Sphinx to use the docstring as is, without any formatting.
+
+    Docs from C API descriptions are not always valid reStructuredText,
+    these are valid for Python help() but are not docutils.
+    """
+    in_field = False
+    for line in lines:
+        if line.startswith(':'):
+            in_field = True
+            continue
+        if in_field:
+            stripped = line.lstrip()
+            if stripped.startswith(('-', '*')) and line[:1].isspace():
+                return True
+            if line and not line[0].isspace() and not line.startswith(':'):
+                in_field = False
+        if line.startswith((' ', '\t')):
+            return True
+    return False
+
+
+def process_docstring(app, what, name, obj, options, lines):
+    if not lines or not _needs_literal_docstring(lines):
+        return
+    body = list(lines)
+    lines[:] = ['::', ''] + [('    ' + line if line else '') for line in body]
+
+
+def setup(app):
+    app.connect('autodoc-process-docstring', process_docstring)