RocketPy documentation

RocketPy uses Sphinx to generate the documentation. Sphinx makes it easy to create documentation for Python projects and it is widely used for Python projects, such as NumPy, Pandas and SciPy.

The ReadTheDocs is used to host the documentation. It is a free service that automatically builds documentation from your sphinx source files and hosts them for free.

RocketPy official documentation is available at https://docs.rocketpy.org.

How to build the documentation in your local machine

When you find yourself modifying the documentation files and trying to see the results, you can build the documentation in your local machine. This is important to check if the documentation is being generated correctly before pushing the changes to the repository.

To build the documentation in your local machine, you need to install a set of requirements that are needed to run the sphinx generator. All these requirements are listed in the requirements.txt file inside the docs folder.

The easiest way to install the requirements and build the documentation is by RocketPy’s Makefile command:

make build-docs

This command will install the requirements and generate the documentation in the docs/_build/html folder.

Note

This requires the make command to be available in your system. Check out GNU Make documentation on how to install it.

To see the documentation, open the docs/_build/html/index.html file in your browser.

Important

Watch out for any introduced warnings or errors that may appear in the terminal when building the documentation. If you find any, fix them before pushing the changes to the repository or at least warn the team about them.

Sometimes you may face problems when building the documentation after several times of building it. This may happen because sphinx does not clean the docs/_build folder before building the documentation again.

One can use the internal Makefile inside the docs folder generated by sphinx to have specific commands to build and clean the documentation.

To clean the docs/_build folder, run the following commands in your terminal:

cd docs/
make clean

After cleaning the docs/_build folder, you can build the documentation again by going back to rocketpy root directory and using the make build-docs command described above.

If the error persists, it may be related to other files, such as the .rst files or the conf.py file.

Danger

Do not modify sphinx internal Makefile or the docs/make.bat files. These files are automatically generated by sphinx and any changes will be lost.

How to integrate the documentation with ReadTheDocs

The documentation is automatically built and hosted by ReadTheDocs. Every time a commit is pushed to selected branches of the repository (such as master and develop), ReadTheDocs will build the documentation and host it automatically.

However, custom branches need to be manually added. If you need to have your branch available on ReadTheDocs, ask to a maintainer for help.

The connection between the GitHub repository and the ReadTheDocs project is already configured and defined in the readthedocs.yml file, available at the root of the repository.

Note

You need admin permissions to configure the ReadTheDocs project. Ask the team for help if you don’t have admin permissions.