diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 18fdfbd1..c8208a15 100644
--- a/.github/workflows/ci.yaml
+++ b/.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
diff --git a/.gitignore b/.gitignore
index 88aee58f..5d9904d5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,3 @@
*.swp
*.pyc
__pycache__/
-*/doc/html/
-*/doc/manifest.yaml
diff --git a/core/doc/Doxyfile b/core/doc/Doxyfile
new file mode 100644
index 00000000..73392132
--- /dev/null
+++ b/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*
diff --git a/core/doc/api.rst b/core/doc/api.rst
index a1a47001..470cb5db 100644
--- a/core/doc/api.rst
+++ b/core/doc/api.rst
@@ -12,3 +12,5 @@ API reference
moveit.task_constructor
pymoveit_mtc.core
pymoveit_mtc.stages
+
+.. doxygenindex::
diff --git a/core/doc/conf.py b/core/doc/conf.py
index 7e8f52bb..5337a5d8 100644
--- a/core/doc/conf.py
+++ b/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
-# -- Path setup --------------------------------------------------------------
+
+from lxml import etree
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+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 @@ import sphinx_rtd_theme
# 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 @@ author = "Michael Görner, Robert Haschke"
# |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 @@ language = None
# 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 @@ exclude_patterns = ["python/pybind11", "_templates"]
# 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 @@ todo_include_todos = False
# 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 @@ html_theme = "sphinx_rtd_theme"
# 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 @@ htmlhelp_basename = "mtcdoc"
# 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)
diff --git a/core/doc/requirements.txt b/core/doc/requirements.txt
new file mode 100644
index 00000000..b8c6a92b
--- /dev/null
+++ b/core/doc/requirements.txt
@@ -0,0 +1,5 @@
+breathe
+furo
+lxml
+sphinx
+sphinx-copybutton
diff --git a/core/package.xml b/core/package.xml
index c6014f6b..0459fd54 100644
--- a/core/package.xml
+++ b/core/package.xml
@@ -3,8 +3,9 @@
0.0.0
MoveIt Task Pipeline
- https://github.com/ros-planning/moveit_task_constructor/issues
+ https://github.com/ros-planning/moveit_task_constructor
https://github.com/ros-planning/moveit_task_constructor
+ https://github.com/ros-planning/moveit_task_constructor/issues
BSD
Michael Goerner