From 9c8971cc0fec866fa42312a1598a61a35676ac13 Mon Sep 17 00:00:00 2001 From: Gui-FernandesBR Date: Thu, 2 Nov 2023 20:47:54 -0300 Subject: [PATCH 1/4] DOC: Add documentation on how to build the RocketPy docs locally --- docs/development/build_docs.rst | 97 +++++++++++++++++++++++++++++++++ docs/development/index.rst | 1 + 2 files changed, 98 insertions(+) create mode 100644 docs/development/build_docs.rst diff --git a/docs/development/build_docs.rst b/docs/development/build_docs.rst new file mode 100644 index 000000000..1234ce227 --- /dev/null +++ b/docs/development/build_docs.rst @@ -0,0 +1,97 @@ +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. + +To install the requirements, run the following command in your terminal: + +```bash +cd docs +pip install -r requirements.txt +``` + +After installing the requirements, you can build the documentation by running +the following command in your terminal: + +```bash +make html +``` + +The file named `Makefile` contains the commands to build the documentation. +The `make html` command will generate the documentation in the `docs/_build/html` +folder. + +To see the documentation, open the `docs/_build/html/index.html` file in your +browser. + +.. note:: 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: + +```bash +make clean +``` + +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 `.rst` +files or the `conf.py` file. + +.. danger:: 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. + +.. note:: You need admin permissions to configure the ReadTheDocs project. Ask + the team for help if you don't have admin permissions. + diff --git a/docs/development/index.rst b/docs/development/index.rst index b13769e56..694d8f4af 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -8,5 +8,6 @@ Contributing to RocketPy Running RocketPy as a Developer GitHub Workflow for RocketPy Hackathon 2022 Style Guide + Building the Documentation This section is still a work in progress. Here you will find information on how to contribute to our code base. \ No newline at end of file From 3b10a35aa3beb225c67f62fd1cba82890cf12858 Mon Sep 17 00:00:00 2001 From: Gui-FernandesBR Date: Thu, 2 Nov 2023 21:05:29 -0300 Subject: [PATCH 2/4] BUG: Update build_docs.rst link in development index.rst --- docs/development/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/index.rst b/docs/development/index.rst index 694d8f4af..a4bff85c8 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -8,6 +8,6 @@ Contributing to RocketPy Running RocketPy as a Developer GitHub Workflow for RocketPy Hackathon 2022 Style Guide - Building the Documentation + Building the Documentation This section is still a work in progress. Here you will find information on how to contribute to our code base. \ No newline at end of file From 3676578cfdff19830790c8440d11fe4d948319bd Mon Sep 17 00:00:00 2001 From: MateusStano Date: Mon, 6 Nov 2023 22:02:34 +0100 Subject: [PATCH 3/4] DOCS: change italics to inline code --- docs/development/build_docs.rst | 36 ++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/development/build_docs.rst b/docs/development/build_docs.rst index 1234ce227..cf2ad87ac 100644 --- a/docs/development/build_docs.rst +++ b/docs/development/build_docs.rst @@ -28,8 +28,8 @@ 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. +All these requirements are listed in the ``requirements.txt`` file inside the +``docs`` folder. To install the requirements, run the following command in your terminal: @@ -45,8 +45,8 @@ the following command in your terminal: make html ``` -The file named `Makefile` contains the commands to build the documentation. -The `make html` command will generate the documentation in the `docs/_build/html` +The file named ``Makefile`` contains the commands to build the documentation. +The ``make html`` command will generate the documentation in the ``docs/_build/html`` folder. To see the documentation, open the `docs/_build/html/index.html` file in your @@ -59,39 +59,39 @@ browser. 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 +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: +To clean the ``docs/_build`` folder, run the following command in your terminal: ```bash make clean ``` -After cleaning the `docs/_build` folder, you can build the documentation again -by running the `make html` command. +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 `.rst` -files or the `conf.py` file. +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 the Makefile or the make.bat files. These files are +.. danger:: 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 +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 +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 +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 +.. note:: You need admin permissions to configure the `ReadTheDocs` project. Ask the team for help if you don't have admin permissions. From 99d7789f8d01797252ac492ed2d730f577533353 Mon Sep 17 00:00:00 2001 From: MateusStano Date: Mon, 6 Nov 2023 22:03:03 +0100 Subject: [PATCH 4/4] DOCS: add bash code blocks --- docs/development/build_docs.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/development/build_docs.rst b/docs/development/build_docs.rst index cf2ad87ac..5b60b0c99 100644 --- a/docs/development/build_docs.rst +++ b/docs/development/build_docs.rst @@ -31,25 +31,25 @@ requirements that are needed to run the sphinx generator. All these requirements are listed in the ``requirements.txt`` file inside the ``docs`` folder. -To install the requirements, run the following command in your terminal: +To install the requirements, navigate the terminal to the ``docs`` folder and +run the following command: -```bash -cd docs -pip install -r requirements.txt -``` +.. code-block:: bash + + pip install -r requirements.txt After installing the requirements, you can build the documentation by running the following command in your terminal: -```bash -make html -``` +.. code-block:: bash + + make html The file named ``Makefile`` contains the commands to build the documentation. The ``make html`` command will generate the documentation in the ``docs/_build/html`` folder. -To see the documentation, open the `docs/_build/html/index.html` file in your +To see the documentation, open the ``docs/_build/html/index.html`` file in your browser. .. note:: Watch out for any warnings or errors that may appear in the terminal @@ -63,9 +63,9 @@ 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: -```bash -make clean -``` +.. code-block:: bash + + make clean After cleaning the ``docs/_build`` folder, you can build the documentation again by running the ``make html`` command.