Tutorial: make a contribution to the documentation¶
In this tutorial we will make a contribution to the documentation of Nashpy.
Forking the repository¶
Navigate to the Github repository for Nashpy:
https://github.com/drvinceknight/Nashpy. This is the hub for development of the
source code. You cannot make modification to this copy of the source code so you
need to create your own copy under your Github account. You do this by creating
a fork. Do this by clicking the
Fork button and following the
Cloning the repository¶
Once we have a fork of the repository on your Github account, create a copy of it to your computer. This is called cloning. Do this by clicking the Code button and copying the address of the repository to your clipboard:
If you have not installed
git go to https://git-scm.com and install.
Now to create a clone of the source code open your command line tool and type
the following (replace
<your username> with your Github username):
$ git clone https://github.com/<your username>/Nashpy.git
This will download the source code to your computer:
$ git clone https://github.com/<your username>/Nashpy.git Cloning into 'Nashpy'... remote: Enumerating objects: 1813, done. remote: Counting objects: 100% (362/362), done. remote: Compressing objects: 100% (225/225), done. remote: Total 1813 (delta 160), reused 233 (delta 79), pack-reused 1451 Receiving objects: 100% (1813/1813), 439.94 KiB | 2.67 MiB/s, done. Resolving deltas: 100% (905/905), done.
Creating a branch¶
In order to modify the source code you must create a new branch. After cloning, first change directory in to the Nashpy source code:
$ cd Nashpy
Now, to keep the changes you are about to make separate from the
source code, create a branch:
$ git branch add-name-to-contributors-list
Now checkout to that branch:
$ git checkout add-name-to-contributors-list
Modifying the documentation¶
Using your preferred editor, open the file
Nashpy/docs/contributing/reference/contributors/index.rst. If you do not
have a preferred editor Visual Studio Code is
Now add you name to the file (replace
with your Github username):
List of contributors -------------------- - `@drvinceknight <https://github.com/drvinceknight>`_ - `@<your username> <https://github.com/<your username>`_
Checking the modification¶
To build the documentation, first create a virtual environment specifically for purposes to work on Nashpy:
$ python -m venv env
This creates a directory
env which holds a separate version of python.
To tell your command line tool to now use this version:
On Linux or macOS type:
$ source env/bin/activate
On Windows type:
Now install the Nashpy software in to this environment:
$ python -m pip install flit $ python -m flit install --symlink
To build the documentation:
$ cd docs $ sphinx-build -b html . _build/html Running Sphinx v3.1.2 loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 2 source files that are out of date updating environment: 1 added, 2 changed, 1 removed reading sources... [100%] contributing/tutorial/index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex py-modindexdone highlighting module code... [100%] nashpy.learning.fictitious_play writing additional pages... searchdone copying images... [100%] _static/contributing/tutorial/cloning/main.png copying static files... ... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded. The HTML pages are in _build/html.
You can open
_build/html/index.html in a browser to see the
documentation locally which should include the changes you made.
Running the test suite¶
You can run the entire test suite which will check that this modification has not caused any problems:
$ python -m pip install tox $ python -m tox
Committing the change¶
Now you need to stage this file:
$ git add docs/contributing/reference/contributors/index.rst
Now commit this file:
$ git commit
This will open a text editor where you can write your commit title and message:
Add <your username> to list of contributors I am doing the contribution tutorial.
Closing the editor will commit the changes you made.
Pushing the change to Github¶
Now that all that is done, you are going to send the changes back to your copy of the source code on Github:
$ git push origin add-name-to-contributors-list
Opening a Pull Request¶
You now have 2 copies of the modified source code of Nashpy. One locally on your computer, the other under your Github account. In order to include those changes in to the main source code of Nashpy you will open a Pull request.
To do this, go to your fork of the Nashpy repository:
https://github.com/<your username>/Nashpy. You should see a
Compare and Pull Request button:
Once you have clicked on that, you can review your changes and then eventually
Create pull request to create the Pull Request.
Making further modifications¶
Once a Pull Request is opened, a number of automated checks will start. This will check the various software tests but also build a viewable version of the documentation.
You can click on the corresponding
details button to see any of these:
Your modification will also be reviewed:
To make any required changes, modify the files.
Then stage and commit the files:
$ git add docs/contributing/reference/contributors/index.rst $ git commit
This will open a text editor where you can write your commit title and message (similarly to before).
Once this is done, push the code to Github which will automatically update the pull request:
$ git push origin add-name-to-contributors-list
This final process of making further modifications might repeat itself and eventually the Pull Request will be merged and your changes included in the main version of the Nashpy source code.