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
To install the requirements, navigate the terminal to the
docs folder and
run the following command:
pip install -r requirements.txt
After installing the requirements, you can build the documentation by running the following command in your terminal:
The file named
Makefile contains the commands to build the documentation.
make html command will generate the documentation in the
To see the documentation, open the
docs/_build/html/index.html file in your
Watch out for any 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.
To clean the
docs/_build folder, run the following command in your terminal:
After cleaning the
docs/_build folder, you can build the documentation again
by running the
make html command.
If the error persists, it may be related to other files, such as the
files or the
Do not modify the Makefile or the
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 the repository, ReadTheDocs will build the documentation and host it automatically. This includes other branches besides the master branch. However, the documentation will only be available for the master branch, and you need to configure the ReadTheDocs project to build the documentation for other branches.
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.
You need admin permissions to configure the ReadTheDocs project. Ask the team for help if you don’t have admin permissions.