DOC: improvements to developers documentation

Gui-FernandesBR · Gui-FernandesBR · commit f9b34b9974f6 · 2024-11-17T23:39:42.000-03:00
diff --git a/docs/development/first_pr.rst b/docs/development/first_pr.rst
@@ -0,0 +1,70 @@
+Your first Pull Request (PR)
+============================
+
+This page describes a few steps to help you get started with your first PR to RocketPy.
+We are excited to have you here!
+
+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
+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
+something that is not in line with the project's goals.
+
+If you want to develop a new feature that is not in the issues list, please open
+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.
+
+
+
+Creating a new branch
+---------------------
+
+At your local machine, ...
+
+Opening the PR
+--------------
+
+When you open a PR, you should:
+
+* Use labels to help maintainers understand what the PR is about.
+* Link any issue that may be closed when the PR is merged.
+
+
+Remember, the PR is yours, not ours! You should keep track of it and update it as needed.
+
+
+Continuous Integration (CI)
+---------------------------
+
+There are several automation on our repository to help us maintain the code quality.
+
+Currently, our CI pipeline runs the following checks:
+
+* **Linting**: we run `flake8`, `pylint`, `black` and `isort` on top of your latest commit in order to check for code style issues. To understand more about these tools, please read ...
+* **Testing**: we run the tests defined in the `tests` folder to make sure your changes do not break any existing functionality. The tests will be executed 6 times, each time with a different Python version (the oldest and newest supported version) and with three different operating systems (Windows, Linux and MacOS).
+* **Coverage**: based on the tests results, we also check the code coverage. There is an automation to check if the code coverage increased or decreased with your PR. It also points
+
+Once you open your PR or commit and push to your branch, the CI will be initialized.
+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.
+
+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.
+
+.. note::
+
+    In the future we would like to automate the CHANGELOG update, but for now \
+    it is a manual process, unfortunately.
+
diff --git a/docs/development/index.rst b/docs/development/index.rst
@@ -1,14 +1,27 @@
 Contributing to RocketPy
 ========================
 
+Here you will find information on how to contribute to our code base.
+RocketPy is an open-source project and we welcome contributions from everyone.
+There are a few guidelines we would like to share with you to make the as
+smooth as possible:
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   Setting Up the repository <setting_up.rst>
    Running RocketPy as a Developer <rocketpy_as_developer.rst>
+   Your First Pull Request (PR) <first_pr.rst>
    Style Guide <style_guide>
    Testing Guidelines <testing.rst>
    RocketPy with Docker <docker.rst>
    Building the Documentation <build_docs.rst>
+   Pro Tips <pro_tips.rst>
+
+
+.. important::
 
-This section is still a work in progress. Here you will find information on how to contribute to our code base.
+   Our Development Documentation matters as much as the Usage Documentation to us. \
+   In case you find any trouble when following this guide, please let us know so \
+   we can improve it.
diff --git a/docs/development/pro_tips.rst b/docs/development/pro_tips.rst
@@ -0,0 +1,88 @@
+Pro Tips
+========
+
+Last but not least, here are some pro tips that can help you to be more
+productive when developing in the project (or any other project).
+
+
+Makefile
+--------
+
+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).
+
+These commands are meant to be system agnostic, so you can run them on any
+Operational System (OS).
+
+Knowing your editor
+-------------------
+
+Something we usually notice on beginners is that they don't know all the power
+their editor can provide. Knowing your editor can save you a lot of time and
+make you more productive.
+
+As stated earlier, we recommend using VS Code as your editor, as most of the
+RocketPy developers use it. Therefore it is easier to help you if you are using
+the same editor.
+
+Some of the features that can help you are:
+
+...
+
+Extensions
+----------
+
+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
+productive.
+
+
+Code assistance
+---------------
+
+Artificial Intelligence (AI) assistance has becoming more and more common in
+software development.
+Some editors have AI assistance built-in.
+Famous options are GitHub Copilot, and
+
+At this repo, the use of AI tools is welcome, we don't have any restrictions
+against it.
+
+A few possible applications of AI tools are:
+
+* Writing documentation.
+* Writing tests.
+* Getting explanations of code sections.
+
+.. tip::
+
+    As of today, November 2024, GitHub Copilot still provides free access for \
+    university email addresses. We can't guarantee this will still be the case \
+    when you are reading this, so check the GitHub Copilot website for more \
+    information.
+
+
+If you are against the use of AI tools, do not worry, you can still contribute
+to the project without using them.
+
+
+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
+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.
diff --git a/docs/development/rocketpy_as_developer.rst b/docs/development/rocketpy_as_developer.rst
@@ -27,6 +27,13 @@ For example, to open VS Code type on terminal
 
 Alternatively, you can open the folder directly through your editor's interface.
 
+.. tip::
+
+    Although it is not mandatory, we recommend using VS Code as your editor, as \
+    most (to not say all) of the RocketPy developers use it. Therefore it is easier \
+    to help you if you are using the same editor.
+
+
 Preparing directory for code editing
 ====================================
 
@@ -129,7 +136,7 @@ The motor class contains information about the thrust curve and uses some geomet
 .. code-block:: python
 
     Pro75M1670 = SolidMotor(
-        thrust_source="../data/motors/cesaroni/Cesaroni_M1670.eng", #copy here the path to the thrust source file
+        thrust_source="../data/motors/cesaroni/Cesaroni_M1670.eng",  # NOTE: update the path to the thrust source file
         burn_time=3.9,
         grain_number=5,
         grain_separation=5 / 1000,
diff --git a/docs/development/setting_up.rst b/docs/development/setting_up.rst
@@ -0,0 +1,56 @@
+Setting Up RocketPy as a Developer
+==================================
+
+
+Forking the repository
+----------------------
+
+The first step is to fork the RocketPy repository. You can do this by clicking
+the **Fork** button on the top right corner of the repository page on GitHub.
+
+By default, the fork will only have the `master` branch. You should also fork
+the `develop` branch. You can do this by going to the `develop` branch on the
+RocketPy repository before clicking the **Fork** button.
+
+.. IMPORTANT: this part is usually not so clear.
+
+.. important::
+
+    Our `master` branch is the stable branch, and the `develop` branch is the \
+    development branch. You should always create your PRs against the `develop` \
+    branch, unless it is a really important hotfix.
+
+
+Cloning the Repository
+----------------------
+
+
+Installation
+------------
+
+
+pip install -e .
+pip install -r requirements-optional.txt
+pip install -r requirements-tests.txt
+
+
+Navigating through the project
+------------------------------
+
+git checkout ...
+
+
+Running a flight simulation
+---------------------------
+
+Please see the other page... (link the other page)
+
+Running the tests
+-----------------
+
+make pytest
+
+make pytest-slow
+
+make coverage-report
+
diff --git a/docs/development/style_guide.rst b/docs/development/style_guide.rst
@@ -1,31 +1,38 @@
 Style Guide
 ===========
 
-This page describes code, documentation and git branching styles used throughout RocketPy's development.
+This page describes code, documentation and git branching styles used throughout
+RocketPy's development.
 
 Code Style
 ----------
 
-We mostly follow the standard Python style conventions as described here: `Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008/>`_
+We mostly follow the standard Python style conventions as described here:
+`Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008/>`_
 
 Naming Conventions
 ^^^^^^^^^^^^^^^^^^
-RocketPy was, unfortunately, initially coded using `Camel Case <https://en.wikipedia.org/wiki/Camel_case>`_.
+RocketPy was, unfortunately, initially coded using
+`Camel Case <https://en.wikipedia.org/wiki/Camel_case>`_.
 However, PEP8 specifies the following::
 
-    Function names should be lowercase, with words separated by underscores as necessary to improve readability.
+    Function names should be lowercase, with words separated by underscores as \
+    necessary to improve readability.
     Variable names follow the same convention as function names.
 
     mixedCase is allowed only in contexts where that is already the prevailing style (e.g. threading.py), to retain backwards compatibility.
 
 Therefore, `Snake Case <https://en.wikipedia.org/wiki/Snake_case>`_ is preferred.
-For this reason, RocketPy is being converted from Camel to Snake as of version ``1.0.0``.
-New contributions should strive to follow Snake case as well.
+For this reason, RocketPy has being fully converted from `CamelCase` to `snake_case` as of version ``1.0.0``.
+New contributions should strive to follow `snake_case` case as well.
 
-Furthermore, when it comes to naming new variables, functions, classes or anything in RocketPy, always try to use descriptive names.
+Furthermore, when it comes to naming new variables, functions, classes or
+anything in RocketPy, always try to use descriptive names.
 
-As an example, instead of using `a` or `alpha` as a variable for a rocket's angle of attack, `angle_of_attack` is preferred.
-Such descriptive names make the code significantly easier to understand, review and maintain.
+As an example, instead of using `a` or `alpha` as a variable for a rocket's
+angle of attack, `angle_of_attack` is preferred.
+Such descriptive names make the code significantly easier to understand, review
+and maintain.
 
 In summary:
 
@@ -38,18 +45,38 @@ In summary:
     angle_of_attack = 0.2 # in rad
 
 
-Linting
-^^^^^^^
-As far as line wrapping, parentheses, calling chains and other code style related matter goes, RocketPy currently employs `Black style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_.
+Linting and formatting
+^^^^^^^^^^^^^^^^^^^^^^
+
+As far as line wrapping, parentheses, calling chains and other code style
+related matter goes, RocketPy currently employs `Black style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_.
 Installing Black and running it before submitting a pull request is highly recommend.
 Currently, there are pull request tests in place to enforce that Black style is used.
 
+Aside from Black, RocketPy also uses `Flake8 <https://flake8.pycqa.org/en/latest/>`_
+and `Pylint <https://pylint.pycqa.org/en/latest/>`_ to check for code style issues.
+
+Running these commands before submitting a pull request is also highly recommended:
+
+.. code-block:: bash
+
+    make flake8
+    make pylint
+
+These commands will check for any code style issues in the codebase.
+The `flake8` command will throw a report directly to the console, while the
+`pylint` command will create a `.pylint_report.txt` file in the root directory,
+which you can open to see the report.
+
+
 
 Documentation Style
 -------------------
 
-Every class, method, attribute and function added to RocketPy should be well documented using docstrings.
-RocketPy follows NumPy style docstrings, which are very well explained here: `NumPyDoc Style Guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
+Every class, method, attribute and function added to RocketPy should be well
+documented using docstrings.
+RocketPy follows NumPy style docstrings, which are very well explained here:
+`NumPyDoc Style Guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
 
 Git Style
 ---------
