Skip to content

Commit

Permalink
consistent typesetting and capitalization for "rosdoc2"
Browse files Browse the repository at this point in the history
  • Loading branch information
ottojo committed Mar 19, 2024
1 parent 5c0230c commit a56aa75
Showing 1 changed file with 6 additions and 6 deletions.
12 changes: 6 additions & 6 deletions source/How-To-Guides/Documenting-a-ROS-2-Package.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,12 @@ The tool responsible for generating ROS 2 package docs is `rosdoc2 <https://gith
Sphinx allows freeform written documentation as well as API documentation for python code generated from comments in the code.
The `breathe <https://breathe.readthedocs.io/en/latest/>`__ + `exhale <https://exhale.readthedocs.io/en/latest/>`__ packages allow integration with Doxygen, to include autogenerated C++ API documentation as well.

``Rosdoc2`` creates a default configuration for packages with no documentation or configuration at all, and applies options for a uniform theme and integration with other packages.
``rosdoc2`` creates a default configuration for packages with no documentation or configuration at all, and applies options for a uniform theme and integration with other packages.

Building Package Docs
---------------------

To generate the documentation for a package in HTML format with rosdoc2, run:
To generate the documentation for a package in HTML format with ``rosdoc2``, run:

.. code-block:: console
Expand Down Expand Up @@ -89,7 +89,7 @@ If however a ``conf.py`` Sphinx config is found in the ``doc`` subdirectory of t
A custom Sphinx project is required if you want to include a standalone reStructuredText documentation page.
A standalone documentation page can be used to list multiple tutorials and guides; if that's something you want for your package you'll need to create a custom Sphing project.

``Rosdoc2`` provides additional settings to ``conf.py`` and overrides some.
``rosdoc2`` provides additional settings to ``conf.py`` and overrides some.
Information about changes done to the Sphinx settings are logged to the console with a ``[rosdoc2]`` prefix.

Doxyfile
Expand Down Expand Up @@ -126,7 +126,7 @@ In order for autodoc to find the Python modules in your package, it must be adde
sys.path.insert(0, os.path.abspath('.'))
Since rosdoc2 wraps the custom ``conf.py`` with more configuration from a script which will be placed in the package In this case the ``.`` path in ``os.path.abspath`` refers to the package's directory root, not the package's ``doc`` directory due to the interaction between rosdoc2 and ``conf.py``.
Since ``rosdoc2`` wraps the custom ``conf.py`` with more configuration from a script which will be placed in the package In this case the ``.`` path in ``os.path.abspath`` refers to the package's directory root, not the package's ``doc`` directory due to the interaction between rosdoc2 and ``conf.py``.

By default, package API docs are already reachable through the "Module Index" link that is present on the landing page.
For the API docs to also appear in the table of contents, simply add a link to the ``modules`` page to your ``index.rst``:
Expand Down Expand Up @@ -217,7 +217,7 @@ This also requires adding ``myst_parser`` to the extensions in ``conf.py``:
CI, docs.ros.org
----------------

The ROS build farm uses rosdoc2 to build the package documentation hosted at ``docs.ros.org/en/<distro>/p/<package>/``.
The ROS build farm uses ``rosdoc2`` to build the package documentation hosted at ``docs.ros.org/en/<distro>/p/<package>/``.
To enable this, the repository containing the documentation must be configured in `rosdistro/<ROS DISTRO>/distribution.yaml <https://github.com/ros/rosdistro/blob/master/rolling/distribution.yaml>`__.
This would usually be the package source repository:

Expand All @@ -240,6 +240,6 @@ On each job page, you can see when a build was last triggered, as well as the st
Further Reading
---------------

* Rosdoc2 readme: https://github.com/ros-infrastructure/rosdoc2/blob/main/README.md
* ``rosdoc2`` readme: https://github.com/ros-infrastructure/rosdoc2/blob/main/README.md
* ROS 2 design document on package documentation: https://design.ros2.org/articles/per_package_documentation.html
* The ROS 2 cookbook: https://github.com/mikeferguson/ros2_cookbook/blob/main/pages/rosdoc2.md

0 comments on commit a56aa75

Please sign in to comment.