Release documentation

Install requirements

Building the ROS Gazebo Gym documentation requires sphinx, the ros_gazebo_gym package and several system and Python packages. you can use rosdep, a package manager for ROS that automates the installation of system and ROS dependencies. To install the required dependencies for building the documentation, you can run the following command inside your Catkin workspace:

rosdep install -t doc --from-paths src --ignore-src -r -y

Alternatively, you can also use the requirements/doc_requirements.txt file to install the Python packages inside your Python environment. This can be done using the following pip command:

pip install -r requirements/doc_requirements.txt

Note

You can also install these requirements in a virtual environment. If you want to do so, you are advised to use the venv package instead of Conda since the latter is known to cause issues when used with ROS. If you use the venv package, please use the --system-site-packages flag when creating the virtual environment. This will ensure all the ROS system packages are available in the virtual environment. This is required because the sphinx package needs to be able to import the ros_gazebo_gym ROS package.

Build the documentation

To build the Python and ROS documentation, go into the docs/ directory and run the make docs command. This command will use rosdoc_lite and sphinx to generate the html documentation inside the docs/build/html directory. If the documentation is successfully built, you can also use the make linkcheck command to check for broken links.

Attention

If you used a virtual environment, ensure you are in the environment where you installed the ros_gazebo_gym package with its dependencies.

Tip

You can also use the make html command to build the documentation. Although warnings and errors are now coloured, it does not produce the accompanying ROS package documentation.

Note

Sometimes the make linkcheck command doesn’t show the results on the stdout. You can also find the results in the docs/build/linkcheck folder.

Deploying

The documentation is automatically built and deployed to the Github Pages site by the Docs workflow when a new version is released. You must create a new release to deploy documentation to the Github Pages. Additionally, you can manually deploy the documentation through the GitHub action interface by running the Docs workflow.