GHA: Build and deploy documentation

.github/workflows/ci.yaml

@@ -8,8 +8,13 @@ on:
   pull_request:
   push:
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
-  default:
+  ici:
     strategy:
       fail-fast: false
       matrix:
@@ -76,6 +81,12 @@ jobs:
         with:
           fixesFile: ${{ env.BASEDIR }}/clang-tidy-fixes.yaml
 
+      - name: Upload ici's target_ws/install folder
+        uses: rhaschke/upload-ici-workspace@main
+        if: success() && matrix.env.CLANG_TIDY
+        with:
+          subdir: target_ws/install
+
       - name: Upload clang-tidy fixes (on failure)
         uses: actions/upload-artifact@v3
         if: failure() && (steps.ici.outputs.clang_tidy_checks)
@@ -102,3 +113,54 @@ jobs:
         if: contains(matrix.env.TARGET_CMAKE_ARGS, '--coverage') && steps.ici.outputs.target_test_results == '0'
         with:
           files: ${{ env.BASEDIR }}/target_ws/coverage.info
+
+  doc:
+    # https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake
+    if: github.repository_owner == 'ros-planning'
+    runs-on: ubuntu-latest
+    needs: ici
+    container:
+      image: moveit/moveit:noetic-source
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+
+      - name: Install dependencies
+        run: |
+          apt-get update -q
+          apt-get install -y doxygen graphviz python3-pip
+          pip install -r core/doc/requirements.txt
+
+      - name: Download ICI workspace
+        uses: rhaschke/download-ici-workspace@main
+
+      - name: Build Documentation
+        shell: bash
+        run: |
+          source ici/setup.bash
+          (cd core/doc; doxygen)
+          sphinx-build core/doc _site
+      - name: Validate links
+        if: false
+        shell: bash
+        run: |
+          source ici/setup.bash
+          sphinx-build -W -b linkcheck core/doc _site
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v1
+
+  # Deployment job
+  deploy:
+    if: github.repository_owner == 'ros-planning'
+    runs-on: ubuntu-latest
+    needs: doc
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -1,5 +1,3 @@
 *.swp
 *.pyc
 __pycache__/
-*/doc/html/
-*/doc/manifest.yaml

core/doc/Doxyfile

@@ -0,0 +1,20 @@
+PROJECT_NAME           = MTC
+INPUT                  = ../include/ ../src/
+RECURSIVE              = YES
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = _doxygenxml
+XML_PROGRAMLISTING     = YES
+
+ALIASES                = "rst=\verbatim embed:rst"
+ALIASES               += "endrst=\endverbatim"
+
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+
+EXCLUDE_SYMBOLS        = *Private
+EXCLUDE_SYMBOLS       += class_
+EXCLUDE_SYMBOLS       += declval*

core/doc/api.rst

@@ -12,3 +12,5 @@ API reference
    moveit.task_constructor
    pymoveit_mtc.core
    pymoveit_mtc.stages
+
+.. doxygenindex::

core/doc/conf.py

@@ -1,20 +1,21 @@
-# -*- coding: utf-8 -*-
-#
 # Configuration file for the Sphinx documentation builder.
 #
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+# This file does only contain a selection of the most common options.
+# For a full list, refer to: http://www.sphinx-doc.org/en/master/config
+
+
+from lxml import etree
+import os
+import subprocess
+import sys
+from pathlib import Path
 
-# -- Path setup --------------------------------------------------------------
+DIR = Path(__file__).parent.resolve()
 
 # 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.
-#
-import os
-import sys
-import sphinx_rtd_theme
+# sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
 
@@ -25,17 +26,21 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "breathe",
+    "sphinx_copybutton",
     "sphinx.ext.autodoc",
-    "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
-    "sphinx_rtd_theme",
     "sphinx.ext.extlinks",
 ]
+breathe_projects = {"mtc": DIR / "_doxygenxml"}
+breathe_default_project = "mtc"
+breathe_domain_by_extension = {"h": "cpp"}
 
 autosummary_generate = True
 autoclass_content = "both"  # Add __init__ doc (ie. params) to class summaries
-html_show_sourcelink = True  # Remove 'view source code' from top of page (for html, not python)
+html_show_sourcelink = False  # Remove 'view source code' from top of page (for html, not python)
 autodoc_inherit_docstrings = True  # If no docstring, inherit from base class
 set_type_checking_flag = True  # Enable 'expensive' imports for sphinx_autodoc_typehints
 add_module_names = False
@@ -62,17 +67,16 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = "0.1.0"
-# The full version, including alpha/beta/rc tags.
-release = "0.1.0"
+# Read version from package.xml
+xml = etree.parse("../package.xml")
+version = str(xml.xpath("/package/version/text()")[0])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -82,7 +86,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["python/pybind11", "_templates"]
+exclude_patterns = [".build", "python/pybind11"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -100,7 +104,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+# pygments_style = 'monokai'
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -116,7 +120,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -195,8 +199,6 @@
 
 # Language to be used for generating the HTML full-text search index.
 # Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
 # html_search_language = 'en'
 
 # A dictionary with options for the search language support, empty by default.
@@ -213,15 +215,32 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
-# Default options for generating documentation.
-autodoc_default_options = {"exclude-members": "ContainerBase, ParallelContainerBase, WrapperBase"}
-
 ros_distro = "noetic"
-ros_docs = "http://docs.ros.org/" + ros_distro + "/api/"
+ros_docs = f"http://docs.ros.org/{ros_distro}/api"
 extlinks = {
-    "rosdocs": (ros_docs + "%s", ""),
-    "msgs": (ros_docs + "moveit_task_constructor/html/msg/%s.html", ""),
-    "moveit_msgs": (ros_docs + "moveit_msgs/html/msg/%s.html", ""),
-    "geometry_msgs": (ros_docs + "geometry_msgs/html/msg/%s.html", ""),
-    "visualization_msgs": (ros_docs + "visualization_msgs/html/msg/%s.html", ""),
+    "rosdocs": (f"{ros_docs}/%s", "%s"),
+    "msgs": (f"{ros_docs}/moveit_task_constructor/html/msg/%s.html", "%s"),
+    "moveit_msgs": (f"{ros_docs}/moveit_msgs/html/msg/%s.html", "%s"),
+    "geometry_msgs": (f"{ros_docs}/geometry_msgs/html/msg/%s.html", "%s"),
+    "visualization_msgs": (f"{ros_docs}/visualization_msgs/html/msg/%s.html", "%s"),
 }
+
+
+def generate_doxygen_xml(app):
+    build_dir = os.path.join(app.confdir, ".build")
+    if not os.path.exists(build_dir):
+        os.mkdir(build_dir)
+
+    print("Running doxygen")
+    try:
+        subprocess.call(["doxygen", "--version"])
+        retcode = subprocess.call(["doxygen"], cwd=app.confdir)
+        if retcode < 0:
+            sys.stderr.write(f"doxygen error code: {-retcode}\n")
+    except OSError as e:
+        sys.stderr.write(f"doxygen execution failed: {e}\n")
+
+
+def setup(app):
+    # Add hook for building doxygen xml when needed
+    app.connect("builder-inited", generate_doxygen_xml)

core/doc/requirements.txt

@@ -0,0 +1,5 @@
+breathe
+furo
+lxml
+sphinx
+sphinx-copybutton

core/package.xml

@@ -3,8 +3,9 @@
 	<version>0.0.0</version>
 	<description>MoveIt Task Pipeline</description>
 
-	<url type="bugtracker">https://github.com/ros-planning/moveit_task_constructor/issues</url>
+	<url type="website">https://github.com/ros-planning/moveit_task_constructor</url>
 	<url type="repository">https://github.com/ros-planning/moveit_task_constructor</url>
+	<url type="bugtracker">https://github.com/ros-planning/moveit_task_constructor/issues</url>
 
 	<license>BSD</license>
 	<maintainer email="[email protected]">Michael Goerner</maintainer>