Documentation pipeline

.azure/publish-documentation.yml

@@ -0,0 +1,72 @@
+#
+# Copyright(c) 2021 ADLINK Technology Limited and others
+#
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License v. 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
+# v. 1.0 which is available at
+# http://www.eclipse.org/org/documents/edl-v10.php.
+#
+# SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+#
+
+#
+# Azure Pipeline specifically for building and publishing documentation
+#
+
+trigger:
+  tags:
+    include:
+    - '*'
+  branches:
+    include:
+    - 'master'
+    - 'releases/*'
+pr: none
+
+pool:
+  vmImage: ubuntu-20.04
+
+steps:
+  - task: UsePythonVersion@0
+    name: install_python
+    displayName: Install Python
+  - bash: |
+      echo "###vso[task.setvariable variable=pip_cache;]$(pip cache dir)"
+    displayName: Obtain pip cache path
+  - task: Cache@2
+    inputs:
+      key: pip-docs | 4 | $(Agent.OS)
+      path: $(pip_cache)
+    name: cache_pip
+    displayName: Retrieve pip cache
+  - bash: |
+      set -e -x
+      cd docs
+      pip install --upgrade pip
+      pip install -r requirements.txt --user --upgrade
+    name: install_sphinx
+    displayName: Install Python dependencies
+  - bash: |
+      set -e -x
+      cd docs
+      mkdir build
+      sphinx-build -b html -j auto -v ./source ./build
+    name: run_sphinx
+    displayName: Run Sphinx
+  - bash: |
+      set -e -x
+      if [ "${BUILD_SOURCEBRANCHNAME}" = "master" ]; then
+        version="latest"
+      else
+        version="$(echo ${BUILD_SOURCEBRANCHNAME} | sed -n -E 's#^.*[vV]?([0-9]+\.[0-9]+)\.[0-9]+((alpha|beta|rc)[0-9]*)?$#\1#p')"
+      fi
+      [ "${version}" != "" ] || exit 1
+      echo "###vso[task.setvariable variable=version;]${version}"
+    name: figure_version
+    displayName: Compute documentation version
+  - task: PublishBuildArtifacts@1
+    displayName: Publish documentation artifact
+    inputs:
+      pathToPublish: docs/build
+      artifactName: 'cyclonedds-python-docs-$(version)'

docs/requirements.txt

@@ -1,2 +1,3 @@
-Sphinx>=3.3.1
-sphinx-rtd-theme==0.5.0
+Sphinx==4.0.2
+sphinx-rtd-theme==0.5.2
+typing_extensions>=3.10

docs/source/conf.py

@@ -1,40 +1,33 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+# -- Configuration file for the Sphinx documentation builder ------------------
+
 import os
 import typing
 
-os.environ['CDDS_NO_IMPORT_LIBS'] = "1"
-typing.TYPE_CHECKING = True
 
-# -- Project information -----------------------------------------------------
+# -- Prevent circular imports in Sphinx ---------------------------------------
+
+import sphinx.builders.html
+import sphinx.builders.latex
+import sphinx.builders.texinfo
+import sphinx.builders.text
+import sphinx.ext.autodoc
 
-project = 'cyclonedds-py'
-copyright = '2020, Thijs Miedema, ADLINK Technology Inc.'
-author = 'Thijs Miedema'
 
+# -- Project information ------------------------------------------------------
 
-# -- General configuration ---------------------------------------------------
+project = 'Eclipse Cyclone DDS Python'
+copyright = '2020, Eclipse Cyclone DDS Python Committers'
+author = 'Eclipse Cyclone DDS Python Committers'
+
+
+# -- General configuration ----------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.extlinks',
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
-    "sphinx.ext.viewcode",
-    'sphinx_markdown_builder'
+    "sphinx.ext.viewcode"
 ]
 autodoc_mock_imports=["ctypes.CDLL", "ddspy"]
 autodoc_member_order = 'bysource'
@@ -51,4 +44,13 @@
 exclude_patterns = ['Thumbs.db', '.DS_Store']
 
 html_theme = 'sphinx_rtd_theme'
-pygments_style = 'friendly'
+pygments_style = 'friendly'
+
+
+# -- Allow documentation building without loading libraries -------------------
+
+os.environ['CDDS_NO_IMPORT_LIBS'] = "1"
+typing.TYPE_CHECKING = True
+
+
+# -- Configuration file for the Sphinx documentation builder ------------------