# rosdoc2
Command-line tool for generating documentation for ROS 2 packages.
## Quick-start
This tool can be viewed from two perspectives: first from the perspective of a user wanting to building documentation for any given ROS 2 package in order to view it, and second from the perspective of package maintainers who need to write their documentation and configure how this tool works on their package.
### Build documentation for a ROS 2 package
To generate the documentation for almost any ROS 2 package, run this command replacing the arguments with appropriate directories:
```
rosdoc2 build \
--package-path ./src/path/to/my_package_name
```
> [!NOTE]
> Please see [Known Issues](#known-issues) if failed.
This command will inspect your package and run various documentation tools based on the configuration of your package.
The package directory that you specify must contain a single ROS 2 package that has a `package.xml` file and optionally a YAML configuration file to configure the doc build process.
There will be an `index.html` file in the output directory which you can open manually, or with this command:
```
rosdoc2 open ./doc_output/index.html
```
For more advanced usage see the documentation.
It may be helpful during rosdoc2 development to run a version of rosdoc2 without installing it. This can be done
(after doing an initial normal install to make sure prerequisites are available) by running, from the rosdoc2 main directory:
```bash
python3 -m rosdoc2.main <options>
```
### Set up a ROS 2 package to be used with this tool
In many cases, C/C++ packages require no configuration, and will work if you simply layout your package in a standard configuration and the tool will do the rest.
However, if you want to provide additional documentation, like a conceptual overview or tutorials, then you will want to provide a Sphinx `conf.py` file and do that documentation in `.rst` files using Sphinx.
Additionally, if you have a Python API then you will want to provide a Sphinx `conf.py`
## Installation
### Prerequisite
```
apt install -y python3-pip git
```
and then, install [ros2_documentation](https://github.com/ros2/ros2_documentation?tab=readme-ov-file#prerequisites) required packages.
### `rosdoc2` installation
`rosdoc2` can be installed locally from the git repository.
Clone the repository, change into the directory, and then run:
```
pip install --user --upgrade .
```
`rosdoc2` will be installed under `~/.local/bin/` directory.
## Documentation
The purpose of this tool is to automate the execution of the various documentation tools when building documentation for ROS 2 packages.
Additionally, it provides several out-of-the-box behaviors to minimize configuration in the packages and to provide consistency across packages.
It aims to support two main cases:
- zero configuration generation of C++ and Python API documents with a landing page for simple packages
- custom Doxyfile (for C++) and Sphinx conf.py file for more extensively configured documentation
The goal for the first case is to allow almost no configuration in packages while still providing some useful documentation, even if there is no Doxyfile, Sphinx conf.py file, or any free form documentation.
The goal for the second case is to allow packages to have free form documentation, additional settings for Doxygen and Sphinx, as well as make it possible for developers to easily invoke Doxygen or Sphinx on their projects manually, without this tool.
In this case, the tool would just automate execution of the tools and provide or override certain additional settings to make it more consistent with other packages, for example configuring the output directory or providing the configuration needed to use cross-references via tag files in Doxygen and inventory files in Sphinx.
### Features
Additionally, the tool aims to enable a few features:
- consistent landing page with basic package information for all packages
- support C++ API documentation extraction via Doxygen
- support Python API documentation extraction via Sphinx
- support free form documentation (prose, tutorial, concept pages, etc) via Sphinx
- support cross-language API cross-referencing via Sphinx using Breathe
- support cross-package documentation cross-referencing between packages via Sphinx
### Roadmap Features
Some features were kept in mind while initially developing this tool, but are not yet implemented.
Including:
- extensible "builders", so that other kinds of documentation tools can be supported in the future
- documenting packages without first building them, if the package does not require it
- packages with generated code, including packages with ROS 2 Messages, need to be built first, but many do not need to be
- using this tool in automated testing and/or CI
### Building Documentation for a Package
### Documenting a Package
What you need to do in order to get basic documentation for your package using this tool is.. nothing.
This tool will extract information from your package's `package.xml` manifest file and generate a landing page for you.
Additionally, if your package is laid out in a standard way then it will automatically run Sphinx and/or Doxygen for you.
However, if you need to place your files in non-standard locations, configure Sphinx and/or Doxygen beyond the defaults, or do something else, you will need to create a `rosdoc2.yaml` file and reference it from your package's `package.xml`.
How to do that, and how to handle some other special cases will follow.
#### Using a `rosdoc2.yaml` file to control how your package is documented
To generate a default config file, run
```
rosdoc2 default_config \
--package-path ./src/path/to/my_package_name
```
TODO
#### Packages with C/C++ API Documentation
The tool uses information from your package's `package.xml` manifest file, and assumes the source files with documentation to be extracted are all in the `include` folder of your packages, based on the package layout conventions for ROS 2:
https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Developer-Guide.html#filesystem-layout
#### Packages with Python API Documentation
TODO
#### Packages with both Python and C/C++ API Documentation
TODO
#### Packages with ROS 2 Messages and other kinds of Interfaces
TODO
### Theory of Operation
It might be helpful, in some cases, to understand how this tool functions.
The tool follows these steps:
- Inspect the `package.xml` of the package for any rosdoc2 specific configurations.
- Note: if none are found, a default configuration which tries to run Sphinx and Doxygen is used.
- Note: one of the things that the configuration consists of is build stanzas, each represents an instance of a 'builder' and takes the form of `'output subdir': {<settings>}` and are in the 'builders' key.
- Note: the 'output subdir' is a relative directory in the output directory specified when running the tool.
- Generate the content for the "package header" which will either be in the package index page (if enabled) or included by the user's Sphinx project.
- Note: this contains standard information about the package, taken from the package.xml and possibly other sources.
- Generate the documentation. For each builder specified (in order defined):
- Invoke the builder with the associated settings.
- Note: each builder is given a separate output directory so file collisions do not occur during doc generation.
- Attempt to move all files generated into a common output directory.
- Note: if a file or folder already exists when copying, an error occurs. This is done to catch "file collisions" between the builders, which may otherwise happen silently.
- Generate the package index page, if configured to do so.
- Move the resulting files from the common output directory into the output directory specified by the user.
- Note: this step can overwrite existing files, e.g. files from a previous run of the tool, but will not delete files that are no longer generated by the documentation, so you may want to delete the output directory if you remove or rename parts of the documentation.
Some things to note from the above:
- Since the key of the builder stanzas is the output directory, it is not possible to have more than one builder run in a single output directory.
- Since builders are run in the order defined, if one builder depends on the output of another, you need to define them in the correct order.
#### Sphinx Builder
The Sphinx builder will attempt to do a few things to ensure it runs even without any configuration:
- If the `sphinx_sourcedir` is provided, it will assert that it exists and use that.
- If not, it will look for a Sphinx project to exist in the conventional `doc` directory in the root of the package.
- If not, it will set up a temporary Sphinx project and run that against the package.
The final default is in place, even for packages with only C++, so that we can enable cross-referencing between packages using Sphinx and Breathe.
If an existing sphinx project is found, the `conf.py` sphinx configuration will be extended to enable rosdoc2-specific features according to the rosdoc2 configuration.
Additionally, the `project`, `author`, `release` and `version` options are populated from package.xml if they are not specified in `conf.py`.
#### Doxygen Builder
The Doxygen builder will attempt to run even with no additional configuration, following these steps:
- If the `doxyfile` setting is provided, it will assert that it exists and use it.
- If not, it will look for a `Doxyfile` in the package's root directory, and use that if it exists.
- If not, it will look for the conventional `include` directory, if it exists it will set up a default Doxygen file and try to document the headers in `include`.
The final default is a best effort to document the headers (assumed to be the public interface for most C++ packages).
## Get in touch
TODO
## Testing
To install rosdoc2 prerequisites for testing, run
```
pip install --user --upgrade .[test]
```
You probably want to test rosdoc2 using code in a local directory rather than
re-running install every time you do a change. To do this, run (from the directory
containing this README):
```
python3 -m pytest
```
If you want to see more output, try the ```-rP``` and/or ```--log-level=DEBUG``` option.
To limit to a particular test, for example the test of "full_package", use ```-k full_package```
Combining these as an example, to get detailed output from the full_package test even for
passed tests, run:
```
python3 -m pytest -rP --log-level=DEBUG -k full_package
```
## Contributing
TODO
## Known Issues
| Description / Error Message | Issue | Workaround |
|:---|:---:|:---|
| `No module named 'rclpy._rclpy_pybind11'` | [#66](https://github.com/ros-infrastructure/rosdoc2/issues/66) | Do not source colcon workspace. |
Raw data
{
"_id": null,
"home_page": "https://github.com/ros-infrastructure/rosdoc2",
"name": "rosdoc2",
"maintainer": "William Woodall",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "william@openrobotics.org",
"keywords": "rosdoc2",
"author": "William Woodall",
"author_email": "william@openrobotics.org",
"download_url": "https://files.pythonhosted.org/packages/89/39/ca4b687d50c62798ddc77081ae65940797448edc37a3ee9dd929868b241d/rosdoc2-0.2.0.tar.gz",
"platform": null,
"description": "# rosdoc2\n\nCommand-line tool for generating documentation for ROS 2 packages.\n\n## Quick-start\n\nThis tool can be viewed from two perspectives: first from the perspective of a user wanting to building documentation for any given ROS 2 package in order to view it, and second from the perspective of package maintainers who need to write their documentation and configure how this tool works on their package.\n\n### Build documentation for a ROS 2 package\n\nTo generate the documentation for almost any ROS 2 package, run this command replacing the arguments with appropriate directories:\n\n```\nrosdoc2 build \\\n --package-path ./src/path/to/my_package_name\n```\n\n> [!NOTE]\n> Please see [Known Issues](#known-issues) if failed.\n\nThis command will inspect your package and run various documentation tools based on the configuration of your package.\n\nThe package directory that you specify must contain a single ROS 2 package that has a `package.xml` file and optionally a YAML configuration file to configure the doc build process.\n\nThere will be an `index.html` file in the output directory which you can open manually, or with this command:\n\n```\nrosdoc2 open ./doc_output/index.html\n```\n\nFor more advanced usage see the documentation.\n\nIt may be helpful during rosdoc2 development to run a version of rosdoc2 without installing it. This can be done\n(after doing an initial normal install to make sure prerequisites are available) by running, from the rosdoc2 main directory:\n```bash\npython3 -m rosdoc2.main <options>\n```\n\n### Set up a ROS 2 package to be used with this tool\n\nIn many cases, C/C++ packages require no configuration, and will work if you simply layout your package in a standard configuration and the tool will do the rest.\n\nHowever, if you want to provide additional documentation, like a conceptual overview or tutorials, then you will want to provide a Sphinx `conf.py` file and do that documentation in `.rst` files using Sphinx.\n\nAdditionally, if you have a Python API then you will want to provide a Sphinx `conf.py`\n\n## Installation\n\n### Prerequisite\n\n```\napt install -y python3-pip git\n```\n\nand then, install [ros2_documentation](https://github.com/ros2/ros2_documentation?tab=readme-ov-file#prerequisites) required packages.\n\n### `rosdoc2` installation\n\n`rosdoc2` can be installed locally from the git repository.\nClone the repository, change into the directory, and then run:\n\n```\npip install --user --upgrade .\n```\n\n`rosdoc2` will be installed under `~/.local/bin/` directory.\n\n## Documentation\n\nThe purpose of this tool is to automate the execution of the various documentation tools when building documentation for ROS 2 packages.\nAdditionally, it provides several out-of-the-box behaviors to minimize configuration in the packages and to provide consistency across packages.\n\nIt aims to support two main cases:\n\n- zero configuration generation of C++ and Python API documents with a landing page for simple packages\n- custom Doxyfile (for C++) and Sphinx conf.py file for more extensively configured documentation\n\nThe goal for the first case is to allow almost no configuration in packages while still providing some useful documentation, even if there is no Doxyfile, Sphinx conf.py file, or any free form documentation.\n\nThe goal for the second case is to allow packages to have free form documentation, additional settings for Doxygen and Sphinx, as well as make it possible for developers to easily invoke Doxygen or Sphinx on their projects manually, without this tool.\nIn this case, the tool would just automate execution of the tools and provide or override certain additional settings to make it more consistent with other packages, for example configuring the output directory or providing the configuration needed to use cross-references via tag files in Doxygen and inventory files in Sphinx.\n\n### Features\n\nAdditionally, the tool aims to enable a few features:\n\n- consistent landing page with basic package information for all packages\n- support C++ API documentation extraction via Doxygen\n- support Python API documentation extraction via Sphinx\n- support free form documentation (prose, tutorial, concept pages, etc) via Sphinx\n- support cross-language API cross-referencing via Sphinx using Breathe\n- support cross-package documentation cross-referencing between packages via Sphinx\n\n### Roadmap Features\n\nSome features were kept in mind while initially developing this tool, but are not yet implemented.\nIncluding:\n\n- extensible \"builders\", so that other kinds of documentation tools can be supported in the future\n- documenting packages without first building them, if the package does not require it\n - packages with generated code, including packages with ROS 2 Messages, need to be built first, but many do not need to be\n- using this tool in automated testing and/or CI\n\n### Building Documentation for a Package\n\n### Documenting a Package\n\nWhat you need to do in order to get basic documentation for your package using this tool is.. nothing.\n\nThis tool will extract information from your package's `package.xml` manifest file and generate a landing page for you.\n\nAdditionally, if your package is laid out in a standard way then it will automatically run Sphinx and/or Doxygen for you.\n\nHowever, if you need to place your files in non-standard locations, configure Sphinx and/or Doxygen beyond the defaults, or do something else, you will need to create a `rosdoc2.yaml` file and reference it from your package's `package.xml`.\nHow to do that, and how to handle some other special cases will follow.\n\n#### Using a `rosdoc2.yaml` file to control how your package is documented\n\nTo generate a default config file, run\n\n```\nrosdoc2 default_config \\\n --package-path ./src/path/to/my_package_name\n```\n\nTODO\n\n#### Packages with C/C++ API Documentation\n\nThe tool uses information from your package's `package.xml` manifest file, and assumes the source files with documentation to be extracted are all in the `include` folder of your packages, based on the package layout conventions for ROS 2:\n\nhttps://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Developer-Guide.html#filesystem-layout\n\n#### Packages with Python API Documentation\n\nTODO\n\n#### Packages with both Python and C/C++ API Documentation\n\nTODO\n\n#### Packages with ROS 2 Messages and other kinds of Interfaces\n\nTODO\n\n### Theory of Operation\n\nIt might be helpful, in some cases, to understand how this tool functions.\n\nThe tool follows these steps:\n\n- Inspect the `package.xml` of the package for any rosdoc2 specific configurations.\n - Note: if none are found, a default configuration which tries to run Sphinx and Doxygen is used.\n - Note: one of the things that the configuration consists of is build stanzas, each represents an instance of a 'builder' and takes the form of `'output subdir': {<settings>}` and are in the 'builders' key.\n - Note: the 'output subdir' is a relative directory in the output directory specified when running the tool.\n- Generate the content for the \"package header\" which will either be in the package index page (if enabled) or included by the user's Sphinx project.\n - Note: this contains standard information about the package, taken from the package.xml and possibly other sources.\n- Generate the documentation. For each builder specified (in order defined):\n - Invoke the builder with the associated settings.\n - Note: each builder is given a separate output directory so file collisions do not occur during doc generation.\n - Attempt to move all files generated into a common output directory.\n - Note: if a file or folder already exists when copying, an error occurs. This is done to catch \"file collisions\" between the builders, which may otherwise happen silently.\n- Generate the package index page, if configured to do so.\n- Move the resulting files from the common output directory into the output directory specified by the user.\n - Note: this step can overwrite existing files, e.g. files from a previous run of the tool, but will not delete files that are no longer generated by the documentation, so you may want to delete the output directory if you remove or rename parts of the documentation.\n\nSome things to note from the above:\n\n- Since the key of the builder stanzas is the output directory, it is not possible to have more than one builder run in a single output directory.\n- Since builders are run in the order defined, if one builder depends on the output of another, you need to define them in the correct order.\n\n#### Sphinx Builder\n\nThe Sphinx builder will attempt to do a few things to ensure it runs even without any configuration:\n\n- If the `sphinx_sourcedir` is provided, it will assert that it exists and use that.\n- If not, it will look for a Sphinx project to exist in the conventional `doc` directory in the root of the package.\n- If not, it will set up a temporary Sphinx project and run that against the package.\n\nThe final default is in place, even for packages with only C++, so that we can enable cross-referencing between packages using Sphinx and Breathe.\n\nIf an existing sphinx project is found, the `conf.py` sphinx configuration will be extended to enable rosdoc2-specific features according to the rosdoc2 configuration.\nAdditionally, the `project`, `author`, `release` and `version` options are populated from package.xml if they are not specified in `conf.py`.\n\n#### Doxygen Builder\n\nThe Doxygen builder will attempt to run even with no additional configuration, following these steps:\n\n- If the `doxyfile` setting is provided, it will assert that it exists and use it.\n- If not, it will look for a `Doxyfile` in the package's root directory, and use that if it exists.\n- If not, it will look for the conventional `include` directory, if it exists it will set up a default Doxygen file and try to document the headers in `include`.\n\nThe final default is a best effort to document the headers (assumed to be the public interface for most C++ packages).\n\n## Get in touch\n\nTODO\n\n## Testing\n\nTo install rosdoc2 prerequisites for testing, run\n```\npip install --user --upgrade .[test]\n```\n\nYou probably want to test rosdoc2 using code in a local directory rather than\nre-running install every time you do a change. To do this, run (from the directory\ncontaining this README):\n```\npython3 -m pytest\n```\nIf you want to see more output, try the ```-rP``` and/or ```--log-level=DEBUG``` option.\nTo limit to a particular test, for example the test of \"full_package\", use ```-k full_package```\n\nCombining these as an example, to get detailed output from the full_package test even for\npassed tests, run:\n```\npython3 -m pytest -rP --log-level=DEBUG -k full_package\n```\n\n\n\n\n## Contributing\n\nTODO\n\n## Known Issues\n\n| Description / Error Message | Issue | Workaround |\n|:---|:---:|:---|\n| `No module named 'rclpy._rclpy_pybind11'` | [#66](https://github.com/ros-infrastructure/rosdoc2/issues/66) | Do not source colcon workspace. |\n\n\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Command line tool to build documentation for ROS packages.",
"version": "0.2.0",
"project_urls": {
"GitHub": "https://github.com/ros-infrastructure/rosdoc2",
"Homepage": "https://github.com/ros-infrastructure/rosdoc2"
},
"split_keywords": [
"rosdoc2"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "079ecb139e45cff46031c32a21a36c52abf1b7ec6bfe42316bceaa3800d0db77",
"md5": "2e8d2f8ec69a61025d7c4823c8ace0df",
"sha256": "76855e16a034a858c7d444f655305cf27fc4566e6169439c2e0053a1ed173fb9"
},
"downloads": -1,
"filename": "rosdoc2-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e8d2f8ec69a61025d7c4823c8ace0df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 47891,
"upload_time": "2024-07-12T23:35:16",
"upload_time_iso_8601": "2024-07-12T23:35:16.356706Z",
"url": "https://files.pythonhosted.org/packages/07/9e/cb139e45cff46031c32a21a36c52abf1b7ec6bfe42316bceaa3800d0db77/rosdoc2-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8939ca4b687d50c62798ddc77081ae65940797448edc37a3ee9dd929868b241d",
"md5": "8219fdde59bd3dec6e68fd5b542c1bfd",
"sha256": "56e37ef1db4d5b15f3ef321764ff33c003ccb8d66b6203111e75445e29e1853f"
},
"downloads": -1,
"filename": "rosdoc2-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "8219fdde59bd3dec6e68fd5b542c1bfd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 36541,
"upload_time": "2024-07-12T23:35:18",
"upload_time_iso_8601": "2024-07-12T23:35:18.469128Z",
"url": "https://files.pythonhosted.org/packages/89/39/ca4b687d50c62798ddc77081ae65940797448edc37a3ee9dd929868b241d/rosdoc2-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-12 23:35:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ros-infrastructure",
"github_project": "rosdoc2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rosdoc2"
}
JSON
