mirror of
https://github.com/moveit/moveit_task_constructor.git
synced 2025-09-27 00:29:13 +08:00
GHA: Build and deploy documentation
This commit is contained in:
parent
54e766f139
commit
c9ba6918c8
64
.github/workflows/ci.yaml
vendored
64
.github/workflows/ci.yaml
vendored
@ -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
2
.gitignore
vendored
@ -1,5 +1,3 @@
|
|||||||
*.swp
|
*.swp
|
||||||
*.pyc
|
*.pyc
|
||||||
__pycache__/
|
__pycache__/
|
||||||
*/doc/html/
|
|
||||||
*/doc/manifest.yaml
|
|
||||||
|
20
core/doc/Doxyfile
Normal file
20
core/doc/Doxyfile
Normal 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*
|
@ -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::
|
||||||
|
@ -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)
|
||||||
|
5
core/doc/requirements.txt
Normal file
5
core/doc/requirements.txt
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
breathe
|
||||||
|
furo
|
||||||
|
lxml
|
||||||
|
sphinx
|
||||||
|
sphinx-copybutton
|
@ -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>
|
||||||
|
Loading…
Reference in New Issue
Block a user