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:
|
||||
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
|
||||
|
2
.gitignore
vendored
2
.gitignore
vendored
@ -1,5 +1,3 @@
|
||||
*.swp
|
||||
*.pyc
|
||||
__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
|
||||
pymoveit_mtc.core
|
||||
pymoveit_mtc.stages
|
||||
|
||||
.. doxygenindex::
|
||||
|
@ -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)
|
||||
|
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>
|
||||
<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="me@v4hn.de">Michael Goerner</maintainer>
|
||||
|
Loading…
Reference in New Issue
Block a user