Skip to content

Commit e50d646

Browse files
Gui-FernandesBRjuliomachad0phmbressanLucas-Prates
authored
DOC: improvements to developers documentation (RocketPy-Team#732)
* DOC: improvements to developers documentation * MNT: git rename a few files from the root directory * DOC: more upgrades to development docs * DEV: create script to delete local branches that no longer exist on remote * DOC: I followed the step by step, looked at other parts of the documentation, and didn't find anything to correct or improve. I think it's fine as it is. I added a model to requirements.txt, which was missing when I ran the make html command. * DOC: Update developer docs on sphinx building. * DOC: Clarify testing structure on testing docs. * DOC: Re-run docs requirements freeze. * DOC: Introduce Conflicts Guideline and update First PR. * DOC: fixing typos on development docs. * DOC: Solve review comments of dev docs. * DOC: final touches to developers documentation * DOC: update cSpell configuration to enable additional file types * DEV: move docker ignore file --------- Co-authored-by: Julio Machado <[email protected]> Co-authored-by: Pedro Bressan <[email protected]> Co-authored-by: Lucas de Oliveira Prates <[email protected]>
1 parent d0c0f61 commit e50d646

23 files changed

+699
-361
lines changed

‎CITATION.cff ‎.github/CITATION.cff

File renamed without changes.

‎CODEOWNERS ‎.github/CODEOWNERS

File renamed without changes.

‎CODE_OF_CONDUCT.md ‎.github/CODE_OF_CONDUCT.md

File renamed without changes.

‎CONTRIBUTING.md ‎.github/CONTRIBUTING.md

File renamed without changes.

‎.github/clear-local-branches.ps1

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Delete local branches that no longer exists on remote (windows command line)
2+
git branch -vv | Where-Object { $_ -match 'gone\]' } | ForEach-Object { $_.Trim().Split()[0] } | ForEach-Object { git branch -D $_ }

‎.vscode/settings.json

+8-6
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,14 @@
55
"python.testing.unittestEnabled": false,
66
"python.testing.pytestEnabled": true,
77
"autoDocstring.docstringFormat": "numpy",
8-
"cSpell.enableFiletypes": [
9-
"python",
10-
"jupyter",
11-
"markdown",
12-
"restructuredtext"
13-
],
8+
"cSpell.enabledFileTypes": {
9+
"plaintext": true,
10+
"python": true,
11+
"jupyter": true,
12+
"markdown": true,
13+
"tex": true,
14+
"rst": true
15+
},
1416
"cSpell.language": "en-US",
1517
"cSpell.words": [
1618
"Abdulklech",

‎.dockerignore ‎docker/.dockerignore

File renamed without changes.

‎Dockerfile ‎docker/Dockerfile

File renamed without changes.

‎docker-compose.yml ‎docker/docker-compose.yml

File renamed without changes.

‎docs/conf.py

+1
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
"sphinx.ext.napoleon",
4141
"sphinx.ext.viewcode",
4242
"sphinx.ext.mathjax",
43+
"sphinx_tabs.tabs",
4344
"sphinx_copybutton",
4445
"sphinx_design",
4546
"jupyter_sphinx",

‎docs/development/build_docs.rst

+32-29
Original file line numberDiff line numberDiff line change
@@ -31,64 +31,67 @@ requirements that are needed to run the sphinx generator.
3131
All these requirements are listed in the ``requirements.txt`` file inside the
3232
``docs`` folder.
3333

34-
To install the requirements, navigate the terminal to the ``docs`` folder and
35-
run the following command:
34+
The easiest way to install the requirements and build the documentation is by
35+
RocketPy's ``Makefile`` command:
3636

3737
.. code-block:: bash
38-
39-
pip install -r requirements.txt
4038
41-
After installing the requirements, you can build the documentation by running
42-
the following command in your terminal:
39+
make build-docs
4340
44-
.. code-block:: bash
45-
46-
make html
41+
This command will install the requirements and generate the documentation in the
42+
``docs/_build/html`` folder.
43+
44+
.. note::
4745

48-
The file named ``Makefile`` contains the commands to build the documentation.
49-
The ``make html`` command will generate the documentation in the ``docs/_build/html``
50-
folder.
46+
This requires the ``make`` command to be available in your system. Check out
47+
GNU Make documentation on how to install it.
5148

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

55-
.. note:: Watch out for any warnings or errors that may appear in the terminal
56-
when building the documentation. If you find any, fix them before
57-
pushing the changes to the repository or at least warn the team about
58-
them.
52+
.. important::
53+
54+
Watch out for any introduced warnings or errors that may appear in the terminal
55+
when building the documentation. If you find any, fix them before
56+
pushing the changes to the repository or at least warn the team about
57+
them.
5958

6059
Sometimes you may face problems when building the documentation after several
61-
times of building it.
62-
This may happen because sphinx does not clean the ``docs/_build`` folder before
63-
building the documentation again.
64-
To clean the ``docs/_build`` folder, run the following command in your terminal:
60+
times of building it. This may happen because sphinx does not clean the ``docs/_build``
61+
folder before building the documentation again.
62+
63+
One can use the internal Makefile inside the ``docs`` folder generated by sphinx
64+
to have specific commands to build and clean the documentation.
65+
66+
To clean the ``docs/_build`` folder, run the following commands in your terminal:
6567

6668
.. code-block:: bash
6769
70+
cd docs/
6871
make clean
6972
7073
After cleaning the ``docs/_build`` folder, you can build the documentation again
71-
by running the ``make html`` command.
74+
by going back to rocketpy root directory and using the ``make build-docs`` command
75+
described above.
7276

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

7680
.. danger::
7781

78-
Do not modify the Makefile or the ``make.bat`` files. These files are \
79-
automatically generated by sphinx and any changes will be lost.
82+
Do not modify sphinx internal Makefile or the ``docs/make.bat`` files.
83+
These files are automatically generated by sphinx and any changes will be lost.
8084

8185

8286
How to integrate the documentation with ReadTheDocs
8387
---------------------------------------------------
8488

8589
The documentation is automatically built and hosted by `ReadTheDocs`.
86-
Every time a commit is pushed to the repository, `ReadTheDocs` will build the
87-
documentation and host it automatically.
88-
This includes other branches besides the master branch.
89-
However, the documentation will only be available for the master branch, and you
90-
need to configure the `ReadTheDocs` project to build the documentation for other
91-
branches.
90+
Every time a commit is pushed to selected branches of the repository (such as `master` and `develop`),
91+
`ReadTheDocs` will build the documentation and host it automatically.
92+
93+
However, custom branches need to be manually added. If you need to have your branch
94+
available on `ReadTheDocs`, ask to a maintainer for help.
9295

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

‎docs/development/conflicts.rst

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
Solving Git Conflicts
2+
=====================
3+
4+
What Are Git Conflicts?
5+
-----------------------
6+
7+
Git conflicts occur when Git is unable to automatically merge changes made to the \
8+
same lines of code or when changes overlap in a file across branches.
9+
This often occurs in RocketPy repository when two developers make changes to the same \
10+
file and try to merge them.
11+
In this scenario, Git pauses the operation and marks the conflicting files, \
12+
requiring manual intervention.
13+
14+
Merge vs Rebase
15+
---------------
16+
17+
**Merge**
18+
19+
The ``merge`` operation combines the changes from one branch into another. \
20+
It creates a new commit that marks the merging of the two branches together.
21+
22+
* Retains the full history of both branches.
23+
* Non-linear history shows how changes were combined.
24+
* The history can become cluttered if there are many branches, due to the number of merge commits.
25+
26+
**Rebase**
27+
28+
The ``rebase`` operation integrates changes from one branch into another by reapplying \
29+
the commits on top of the target branch. It results in a more linear history.
30+
31+
* Produces a cleaner, linear commit history.
32+
* Easier to follow the sequence of changes.
33+
* Can rewrite history, leading to potential issues when working on shared branches.
34+
35+
Example Commands
36+
----------------
37+
38+
Let's consider a common scenario from which conflicts can arise:
39+
updating a feature branch with the latest changes from the branch it was created.
40+
Both ``merge`` and ``rebase`` can be used to update the feature branch.
41+
However, the ``rebase`` option is highly recommended to keep a more linear history.
42+
43+
Merge
44+
~~~~~
45+
46+
Suppose you have two branches, ``enh/feature`` that was branched off ``develop``.
47+
It is likely that ``develop`` has been updated since you branched off ``enh/feature``, \
48+
therefore before merging ``enh/feature`` into ``develop``, you should update ``enh/feature`` \
49+
with the latest changes from ``develop``.
50+
51+
One way to do this is by merging ``develop`` into ``enh/feature`` as follows:
52+
53+
.. code-block:: console
54+
55+
git checkout develop
56+
git pull
57+
git checkout enh/feature
58+
git merge develop
59+
60+
If there are conflicts, Git will pause the operation and mark the conflicting files. \
61+
VS Code provides a visual interface to resolve these conflicts in the **Merge Editor**.
62+
If you want to abort the merge, you can use ``git merge --abort``.
63+
64+
Rebase
65+
~~~~~~
66+
67+
Similarly, another way to update ``enh/feature`` with the latest changes from ``develop`` \
68+
is by rebasing ``enh/feature`` onto ``develop`` as follows:
69+
70+
.. code-block:: console
71+
72+
git checkout develop
73+
git pull
74+
git checkout enh/feature
75+
git rebase develop
76+
77+
Differently from merge, if there are conflicts, they must be resolved commit by commit. \
78+
After resolving each step conflicts, you can continue the rebase with ``git rebase --continue``. \
79+
If you want to abort the rebase, you can use ``git rebase --abort``.
80+
81+
When to Use Merge or Rebase
82+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
83+
84+
Generally, the maintainers will inform you which operation to use when merging your PR. \
85+
Notice that there is no wrong way to merge branches, but ``rebase`` is usually preferred \
86+
to keep a more linear history.
87+
88+
Furthermore, it is important to avoid letting conflicts accumulate, since they can become \
89+
harder to resolve. It is recommended to update your feature branch frequently with the latest \
90+
changes from the branch it was branched off.
91+
92+
Solving Conflicts
93+
-----------------
94+
95+
When conflicts arise, Git marks the conflicting files. The file will contain markers like:
96+
97+
.. code-block:: console
98+
99+
<<<<<<< HEAD
100+
Current branch changes
101+
=======
102+
Incoming branch changes
103+
>>>>>>> branch-name
104+
105+
The ``HEAD`` section contains the changes from the current branch, while the ``branch-name`` section \
106+
contains the changes from the incoming branch.
107+
The ``=======`` line separates the two sections.
108+
One can manually edit the file to resolve the conflict, removing the markers and keeping the desired changes, however \
109+
for convenience it is recommended to use a visual tool like the *Merge Editor* in VS Code.
110+
111+
Resolving Conflicts in VS Code
112+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113+
114+
When a conflict occurs, VS Code will open the *Merge Editor* to help you resolve it.\
115+
116+
1. Open the conflicting file (marked with a ``!``).
117+
2. The *Merge Editor* will show the conflicting sections side by side.
118+
3. Click on the ``Accept Current Change`` or ``Accept Incoming Change`` buttons to keep the desired changes, sometimes both changes will be kept or even a manual edit will be necessary.
119+
120+
More details on VS Code interface and conflict solver can be found in `VS Code Docs <https://code.visualstudio.com/docs/sourcecontrol/overview#_3way-merge-editor>`_.
121+
After resolving the conflicts, save the files, make sure all conflicts are resolved, and then \
122+
commit the changes.
123+

0 commit comments

Comments
 (0)