cras_docs_common

Common configuration for CRAS packages documentation.

For Python code, it can generate nice documentation using a custom Sphinx template looking like this:

Sphinx

To document your Python package with Sphinx, add this to your package.xml:

<doc_depend>cras_docs_common</doc_depend>
<doc_depend>rosdoc_lite</doc_depend>
<export>
    <rosdoc config="rosdoc.yaml"/>
</export>

Create file rosdoc.yaml with the following content:

- builder: sphinx
  sphinx_root_dir: doc

Create folder doc, in it create file doc/conf.py with the following content:

# Configuration file for the Sphinx documentation builder.

import os
os.environ['CRAS_DOCS_COMMON_SPHINX_PACKAGE_PATH'] = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# By default, the ctu-vras theme will be used. To use your custom theme, set
# CRAS_DOCS_COMMON_SPHINX_THEME_PATH and CRAS_DOCS_COMMON_SPHINX_HTML_THEME

# include the master configuration
from cras_docs_common.sphinx_docs_conf import *

Create doc/index.rst with this content:

.. documentation master file

|project|
===============================================================================

|description|

Python API
----------

.. toctree::
   :maxdepth: 2

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Finally, create file doc/modules.rst containing the actual modules to be documented, i.e.

cras package
============

Submodules
----------

cras.ctypes\_utils module
-------------------------

.. automodule:: cras.ctypes_utils
   :members:
   :undoc-members:
   :show-inheritance:

The Sphinx config from this package provides some useful shortcuts and automatically links to ROS message definitions on docs.ros.org.

You can try e.g. :roswiki:`cras_py_common`, :rosdep:`rosdep2_api.html`, :tf2_msgs:`TFMessage`, :class:`genpy.Message` or :class:`tf2_msgs.msg.TFMessage`.

It also automatically loads the catkin_sphinx extensions ShLexer and cmake.

Changelog for package cras_docs_common

2.4.5 (2024-11-02)

2.4.4 (2024-09-14)

2.4.3 (2024-09-14)

2.4.2 (2024-09-05)

2.4.1 (2024-09-04)

2.4.0 (2024-09-04)

• Fine-tuned appearance of inline code in Spinx docs and allowed to type inline code by single backticks.
• Contributors: Martin Pecka

2.3.9 (2024-02-27)

• Removed catkin_lint buildfarm hacks.
• Contributors: Martin Pecka

2.3.8 (2024-01-12)

2.3.7 (2024-01-09)

2.3.6 (2024-01-09)

2.3.5 (2023-11-21)

2.3.4 (2023-10-25)

2.3.3 (2023-10-06)

2.3.2 (2023-10-06)

2.3.1 (2023-07-13)

2.3.0 (2023-07-12)

• Increased minimum CMake version to 3.10.2.
• Contributors: Martin Pecka

2.2.3 (2023-06-16)

2.2.2 (2023-05-15)

2.2.1 (2023-05-15)

2.2.0 (2023-04-09)

• Fixed sphinx docs build on Noetic.
• Added support for custom themes.
• Improved readme
• Fixed wrong cross-references created for :ivar: fields by Sphinx.
• Fix providing the custom sphinx theme to packages from this stack on ROS buildfarm.
• Contributors: Martin Pecka

2.1.2 (2023-02-10)

• python3-catkin-sphinx has been released in buster, let's define the dependency for good now.
• Contributors: Martin Pecka

2.1.1 (2023-02-08)

• Revert adding python3-catkin-sphinx dependency until it is released for noetic/buster.
• Contributors: Martin Pecka

2.1.0 (2023-02-08)

• Add python3-catkin-sphinx dependency as it has been added to rosdep.
• Install the Spinx theme files.
• Improved Sphinx CSS.
• Fix tests.
• Temporarily disable python3-catkin-sphinx until the rosdep key exists.
• Added license.
• Added cras_docs_common with a common Sphinx configuration.
• Contributors: Martin Pecka

2.0.10 (2022-11-24 17:43)

2.0.9 (2022-11-24 17:33)

2.0.8 (2022-11-24 16:00)

2.0.7 (2022-11-24 15:38)

2.0.6 (2022-11-24 15:03)

2.0.5 (2022-10-23)

2.0.4 (2022-10-14)

2.0.3 (2022-10-07)

2.0.2 (2022-08-29)

2.0.1 (2022-08-26)