DOC: more upgrades to development docs

Author: Gui-FernandesBR

docs/conf.py

@@ -40,6 +40,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
+    "sphinx_tabs.tabs",
     "sphinx_copybutton",
     "sphinx_design",
     "jupyter_sphinx",

docs/development/conflicts.rst

@@ -0,0 +1,4 @@
+Solving git conflicts
+=====================
+
+...

docs/development/docker.rst

@@ -2,7 +2,7 @@ RocketPy with docker
 =====================
 
 RocketPy does not provide an official docker image, but you can build one
-yourself using the provided `Dockerfile` and `docker-compose.yml` files.
+yourself using the provided ``Dockerfile`` and ``docker-compose.yml`` files.
 
 Benefits
 --------
@@ -20,15 +20,15 @@ using docker are:
 Using docker will be specially important when you are not sure if the code
 additions will still run on different operational systems.
 
-Although we have a set of GitHub actions to test the code on different 
+Although we have a set of GitHub actions to test the code on different
 operational systems every time a pull request is made, it is important to
 submit a PR only after you are sure that the code will run flawlessly,
 otherwise quota limits may be reached on GitHub.
 
 Requirements
 -------------
 
-Before you start, you need to install on your machine: 
+Before you start, you need to install on your machine:
 
 1. `Docker <https://docs.docker.com/get-docker/>`__, to build and run the image.
 2. `Docker Compose <https://docs.docker.com/compose/install/>`__, to compose multiple images at once.
@@ -40,11 +40,11 @@ Build the image
 To build the image, run the following command on your terminal:
 
 .. code-block:: console
-   
+
    docker build -t rocketpy-image -f Dockerfile .
 
 
-This will build the image and tag it as `rocketpy-image` (you can apply another
+This will build the image and tag it as ``rocketpy-image`` (you can apply another
 name of your preference if you want).
 
 An image is a read-only template with instructions for creating a Docker
@@ -82,45 +82,45 @@ Run the unit tests
 --------------------
 
 You might have noticed that the container is running in an isolated environment
-with no access to your machine's files, but the `Dockerfile` already copied the
+with no access to your machine's files, but the ``Dockerfile`` already copied the
 RocketPy repository to the container.
 This means that you can run tests (and simulations!) as if you were running
 RocketPy on your machine.
 
 As simple as that, you can run the unit tests:
 
 .. code-block:: console
-   
+
    pytest
 
 
 To access a list of all available execution options, see the
 `pytest docs <https://docs.pytest.org/en/latest/how-to/usage.html>`__.
 
-Compose docker images 
+Compose docker images
 ---------------------
 
-We also made available a `docker-compose.yml` file that allows you to compose
+We also made available a ``docker-compose.yml`` file that allows you to compose
 multiple docker images at once.
-Unfortunately, this file will not allow you to test the code on different 
+Unfortunately, this file will not allow you to test the code on different
 operational systems at once, since docker images inherits from the host
 operational system.
 However, it is still useful to run the unit tests on different python versions.
 
-Currently, the `docker-compose.yml` file is configured to run the unit tests
+Currently, the ``docker-compose.yml`` file is configured to run the unit tests
 on python 3.9 and 3.12.
 
 To run the unit tests on both python versions, run the following command
 **on your machine**:
 
 .. code-block:: console
-   
+
    docker-compose up
 
 Also, you can check the logs of the containers by running:
 
 .. code-block:: console
-   
+
    docker-compose logs
 
 
@@ -131,7 +131,7 @@ After you're done testing, or if you wish to stop the containers and remove the
 services, use the command:
 
 .. code-block:: console
-   
+
    docker-compose down
 
 
@@ -142,31 +142,31 @@ images created by up.
 Changing to other operational systems
 -------------------------------------
 
-The default image in the `Dockerfile` is based on a Linux distribution.
+The default image in the ``Dockerfile`` is based on a Linux distribution.
 However, you can alter the base image to use different operating systems, though
 the process may require additional steps depending on the OS's compatibility
 with your project setup.
 For instance, certain dependencies or scripts may behave differently or require
 different installation procedures, so use it with caution.
 
-To change the base image, you will need to modify the `FROM` statement in the
-`Dockerfile`.
+To change the base image, you will need to modify the ``FROM`` statement in the
+``Dockerfile``.
 For example, to use a Windows-based image, you might change:
 
 .. code-block:: Dockerfile
-   
+
    FROM python:latest
 
 
 to
 
 .. code-block:: Dockerfile
-   
+
    FROM mcr.microsoft.com/windows/servercore:ltsc2019
 
 
 Please note, the above is just an example, and using a different OS may require
-further adjustments in the `Dockerfile`.
+further adjustments in the ``Dockerfile``.
 We recommend you to see the official Python images on the Docker Hub for
 different OS options: `Docker Hub Python Tags <https://hub.docker.com/_/python/tags>`__.
 

docs/development/first_pr.rst

@@ -8,8 +8,7 @@ Picking an issue
 ----------------
 
 Before you start coding, you should pick an issue to work on. You can find a
-list of issues in the `Issues`_ tab on GitHub.
-.. _Issues: https://github.com/RocketPy-Team/RocketPy/issues
+list of issues in the `Issues` tab on GitHub (https://github.com/RocketPy-Team/RocketPy/issues).
 If you are new hear, it is really recommended that you talk to maintainers
 before starting to work on an issue.
 That way you avoid working on something that is already being worked on or
@@ -20,12 +19,29 @@ a new issue to discuss it with the maintainers before submitting a PR.
 
 Once the issue is assigned to you, you can start working on it.
 
+.. note::
 
+    In order to open an issue at our repo, you must have a GitHub account. \
+    In case you do not want to open an account yet, you can contact the maintainers \
+    through our Discord server. But keep in mind that you you need an account to \
+    open a Pull Request (PR).
 
 Creating a new branch
 ---------------------
 
-At your local machine, ...
+At your local machine,
+
+.. code-block:: console
+
+    git checkout -b <branch_name>
+
+
+.. tip::
+
+    VS Code has a built-in integration with git, this allows you to run git commands \
+    quite easily through the editor's interface. For example, you could search for \
+    "git checkout" in the command palette and run the command from there.
+
 
 Opening the PR
 --------------
@@ -55,16 +71,51 @@ Please correct any issues that may arise from the CI checks.
 
 .. note::
 
-    All the commands we run in the CI pipeline can also be run locally. It is important \
-    that you run the checks locally before pushing your changes to the repository.
+    All the commands we run in the CI pipeline can also be run locally. It is \
+    important that you run the checks locally before pushing your changes to \
+    the repository.
 
 The CHANGELOG file
 ------------------
 
-We keep track of the changes in the `CHANGELOG.md` file. When you open a PR, you should add a new entry to the `Unreleased` section of the file. This entry should simply be the title of your PR.
+We keep track of the changes in the ``CHANGELOG.md`` file.
+When you open a PR, you should add a new entry to the "Unreleased" section of the file. This entry should simply be the title of your PR.
 
 .. note::
 
     In the future we would like to automate the CHANGELOG update, but for now \
     it is a manual process, unfortunately.
 
+
+The review process
+------------------
+
+After you open a PR, the maintainers will review your code.
+This review process is a way to ensure that the code is in line with the project's goals and that it is well written and documented.
+
+The maintainers may ask you to make changes to your code.
+You should address these changes or explain why you think they are not necessary.
+
+This is the best time to learn from the maintainers and improve your coding skills.
+
+In case you do not address the comments in a timely manner, the maintainers may
+either close the PR or make the changes themselves.
+
+
+Merging the PR
+--------------
+
+There are 3 different ways of merging a PR:
+
+1. **Create a merge commit**: this is the default option on GitHub.
+2. **Squash and merge**: this option will squash all your commits into a single one. This is useful when you have many commits and you want to keep the history clean, therefore this is the recommended option.
+3. **Rebase and merge**: this option will add your commits directly to the target branch, without creating a merge commit. This is useful to keep the history linear. However, this
+
+.. note::
+
+    Overall, you will not have permission to merge your PR. The maintainers will \
+    take care of that for you. This is here just for you to understand the process.
+
+All in all, there is no right or wrong way to merge a PR.
+The maintainers will decide which option is the best for the project.
+What you should care tough is about conflicting changes, let's talk about that next.

docs/development/index.rst

@@ -7,12 +7,13 @@ There are a few guidelines we would like to share with you to make the as
 smooth as possible:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
-   Setting Up the repository <setting_up.rst>
+   setting_up.rst
    Running RocketPy as a Developer <rocketpy_as_developer.rst>
    Your First Pull Request (PR) <first_pr.rst>
+   Solving git conflicts <conflicts.rst>
    Style Guide <style_guide>
    Testing Guidelines <testing.rst>
    RocketPy with Docker <docker.rst>

docs/development/pro_tips.rst

@@ -8,16 +8,16 @@ productive when developing in the project (or any other project).
 Makefile
 --------
 
-We have a `Makefile` in the repository that contains some useful commands to
+We have a ``Makefile`` in the repository that contains some useful commands to
 help you with the development process.
 
 Some examples of commands are:
 
 * ``make black``: runs the black formatter on the code.
 * ``make format``: runs the isort and black formatters on the code.
-* ``lint``: runs the flake8 and pylint tools.
-* ``build-docs``: This will build the documentation locally, so you can check if everything is working as expected.
-* ``pytest-slow``: runs only the slow tests (marked with the `@pytest.mark.slow` decorator).
+* ``make lint``: runs the flake8 and pylint tools.
+* ``make build-docs``: This will build the documentation locally, so you can check if everything is working as expected.
+* ``make pytest-slow``: runs only the slow tests (marked with the ``@pytest.mark.slow`` decorator).
 
 These commands are meant to be system agnostic, so you can run them on any
 Operational System (OS).
@@ -35,12 +35,15 @@ the same editor.
 
 Some of the features that can help you are:
 
-...
+1. **Code navigation**: Jump to definitions, find references, etc.
+2. **Integrated tests**: Run tests directly from the editor.
+3. **Python Debugger**: Debug your code directly from the editor.
+4. **GitHub Pull Requests**: Open, review, comment, and merge pull requests directly from the editor
 
 Extensions
 ----------
 
-We have listed some recommended extensions in the `.vscode/extensions.json` file.
+We have listed some recommended extensions in the ``.vscode/extensions.json`` file.
 These are general recommendations based on what our developers usually install
 in their VSCode.
 Obviously, it is not mandatory to install them, but they can help you to be more
@@ -81,8 +84,16 @@ Engaging with the community
 
 The most important part of contributing to an open-source project is engaging
 with the community.
-Our developers are frequently available on the `Discord`_ server, and you can
+Our developers are frequently available on our server, and you can
 ask any questions you may have there.
 Either a question about the project, or a question about how to contribute, or
 even a suggestion of a new feature.
 Any kind of interaction is welcome.
+
+
+.. tip::
+
+    The official supported language in our server is English. \
+    However, the RocketPy Team is lucky to have developers from all around the \
+    world, so you may find people speaking other languages as well. \
+    Don't let the language barrier keep you from engaging with the community.

docs/development/rocketpy_as_developer.rst

@@ -2,7 +2,11 @@
 Introduction to RocketPy
 ========================
 
-This tutorial part shows how to open rocketpy files and run a simple simulation.
+This tutorial section shows how to open rocketpy files and run a simple simulation
+in a local environment.
+It is intended for developers who want to contribute to the project or for users
+who want to run simulations with the library.
+
 
 Opening rocketpy folder
 =======================
@@ -51,11 +55,29 @@ To create the folder, type on the terminal:
 
 And, to add it on .gitignore, type:
 
-.. code-block:: console
+.. tabs::
+
+    .. tab:: Windows
+
+        .. code-block:: console
+
+            echo <folder name>/ >> .gitignore
+
+    .. tab:: Linux
+
+        .. code-block:: console
+
+            echo "<folder name>/" >> .gitignore
+
+    .. tab:: MacOS
+
+        .. code-block:: console
+
+            echo "<folder name>/" >> .gitignore
 
-    echo <folder name>/ >> .gitignore
 
-It is important to remember that all the files inside this folder will not be included in any commit so, if it is important to the solution, do not add them inside it.
+It is important to remember that all the files inside this folder will not be
+included in any commit so, if it is important to the solution, do not add them inside it.
 
 Running a simulation with RocketPy
 ==================================
@@ -78,13 +100,13 @@ Alternatively you can use the following command to pip install the local library
     sys.path.append('../') # if you are using a notebook
     sys.path.append('../rocketpy') # if you are using a script
 
-Import the classes that will be used, in case:
+Import the classes that will be used, in this case:
 
 .. code-block:: python
 
     from rocketpy import Environment, SolidMotor, Rocket, Flight, Function
 
-If it is the first time you are using rocketpy and you do not have all required libraries installed, you could use the command:
+If this is the first time you are using rocketpy and you do not have all required libraries installed, you could use the command:
 
 .. code-block:: python
 
@@ -281,4 +303,3 @@ For example, to access Flight class parameters, you can use:
     help(Flight)
 
 More documentation materials can be found at `read the docs <https://docs.rocketpy.org/en/latest/?badge=latest>`_.
-It can also be found on RocketPy's GitHub page on the badge "docs".