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