GHA: Build and deploy documentation

This commit is contained in:
Robert Haschke 2022-11-25 09:00:11 +01:00
parent 54e766f139
commit c9ba6918c8
7 changed files with 143 additions and 36 deletions

View File

@ -8,8 +8,13 @@ on:
pull_request: pull_request:
push: push:
permissions:
contents: read
pages: write
id-token: write
jobs: jobs:
default: ici:
strategy: strategy:
fail-fast: false fail-fast: false
matrix: matrix:
@ -76,6 +81,12 @@ jobs:
with: with:
fixesFile: ${{ env.BASEDIR }}/clang-tidy-fixes.yaml 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) - name: Upload clang-tidy fixes (on failure)
uses: actions/upload-artifact@v3 uses: actions/upload-artifact@v3
if: failure() && (steps.ici.outputs.clang_tidy_checks) 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' if: contains(matrix.env.TARGET_CMAKE_ARGS, '--coverage') && steps.ici.outputs.target_test_results == '0'
with: with:
files: ${{ env.BASEDIR }}/target_ws/coverage.info 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

2
.gitignore vendored
View File

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

20
core/doc/Doxyfile Normal file
View File

@ -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*

View File

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

View File

@ -1,20 +1,21 @@
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder. # Configuration file for the Sphinx documentation builder.
# #
# This file does only contain a selection of the most common options. For a # This file does only contain a selection of the most common options.
# full list see the documentation: # For a full list, refer to: http://www.sphinx-doc.org/en/master/config
# 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, # 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 # 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. # documentation root, use os.path.abspath to make it absolute, like shown here.
# # sys.path.insert(0, os.path.abspath('.'))
import os
import sys
import sphinx_rtd_theme
# -- General configuration ------------------------------------------------ # -- General configuration ------------------------------------------------
@ -25,17 +26,21 @@ import sphinx_rtd_theme
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones. # ones.
extensions = [ extensions = [
"breathe",
"sphinx_copybutton",
"sphinx.ext.autodoc", "sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.autosummary", "sphinx.ext.autosummary",
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon", "sphinx.ext.napoleon",
"sphinx_rtd_theme",
"sphinx.ext.extlinks", "sphinx.ext.extlinks",
] ]
breathe_projects = {"mtc": DIR / "_doxygenxml"}
breathe_default_project = "mtc"
breathe_domain_by_extension = {"h": "cpp"}
autosummary_generate = True autosummary_generate = True
autoclass_content = "both" # Add __init__ doc (ie. params) to class summaries 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 autodoc_inherit_docstrings = True # If no docstring, inherit from base class
set_type_checking_flag = True # Enable 'expensive' imports for sphinx_autodoc_typehints set_type_checking_flag = True # Enable 'expensive' imports for sphinx_autodoc_typehints
add_module_names = False 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 # |version| and |release|, also used in various other places throughout the
# built documents. # built documents.
# #
# The short X.Y version. # Read version from package.xml
version = "0.1.0" xml = etree.parse("../package.xml")
# The full version, including alpha/beta/rc tags. version = str(xml.xpath("/package/version/text()")[0])
release = "0.1.0"
# The language for content autogenerated by Sphinx. Refer to documentation # The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages. # for a list of supported languages.
# #
# This is also used if you do content translation via gettext catalogs. # This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases. # 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 # There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used: # non-false value, then it is used:
@ -82,7 +86,7 @@ language = None
# List of patterns, relative to source directory, that match files and # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # 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 # The reST default role (used for this markup: `text`) to use for all
# documents. # documents.
@ -100,7 +104,7 @@ exclude_patterns = ["python/pybind11", "_templates"]
# show_authors = False # show_authors = False
# The name of the Pygments (syntax highlighting) style to use. # 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. # A list of ignored prefixes for module index sorting.
# modindex_common_prefix = [] # 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 # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # 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 # 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 # 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. # Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages: # 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' # html_search_language = 'en'
# A dictionary with options for the search language support, empty by default. # 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. # Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} 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_distro = "noetic"
ros_docs = "http://docs.ros.org/" + ros_distro + "/api/" ros_docs = f"http://docs.ros.org/{ros_distro}/api"
extlinks = { extlinks = {
"rosdocs": (ros_docs + "%s", ""), "rosdocs": (f"{ros_docs}/%s", "%s"),
"msgs": (ros_docs + "moveit_task_constructor/html/msg/%s.html", ""), "msgs": (f"{ros_docs}/moveit_task_constructor/html/msg/%s.html", "%s"),
"moveit_msgs": (ros_docs + "moveit_msgs/html/msg/%s.html", ""), "moveit_msgs": (f"{ros_docs}/moveit_msgs/html/msg/%s.html", "%s"),
"geometry_msgs": (ros_docs + "geometry_msgs/html/msg/%s.html", ""), "geometry_msgs": (f"{ros_docs}/geometry_msgs/html/msg/%s.html", "%s"),
"visualization_msgs": (ros_docs + "visualization_msgs/html/msg/%s.html", ""), "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)

View File

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

View File

@ -3,8 +3,9 @@
<version>0.0.0</version> <version>0.0.0</version>
<description>MoveIt Task Pipeline</description> <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="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> <license>BSD</license>
<maintainer email="me@v4hn.de">Michael Goerner</maintainer> <maintainer email="me@v4hn.de">Michael Goerner</maintainer>