This section of the guide cover the installation process and basic usage of the tools needed in order to make changes to the documentation.

You are going to need the following tools:

Install Git

To install Git on your machine refer to this guide.

For a brief introduction to Git usage refer to this guide

Install Python

Python installation is pretty straight forward, refer to the official download page and follow the instruction for your Operating System. As stated above from Python 2.7.9 onward pip comes bundled with Python.

Open the terminal on your machine and type python, the output should resemble the following::

> python
Python 2.7.6 (default, Jun 22 2015, 17:58:13)
[GCC 4.8.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>

Type exit() to exit the Python interpreter

If you get and error back make sure the Python executable is in your PATH.

If you are on Windows follow theese instructions

If you are on Linux locate the Python binary and add it to your PATH, edit your ~/.bashrc and add the following at the end of the file::

export PATH=$PATH:/path/to/the/python-binary

restart your terminal to make the change effective

Now check that you can invoke pip typing pip –version. The output should resemble the following::

pip 1.5.4 from /usr/lib/python2.7/dist-packages (python 2.7)

If you get and error back make sure the pip executable is in your PATH.

Install Sphinx

To install Sphinx on your machine, type the following in your terminal::

pip install Sphinx

Note

If you are on Linux you may need to prefix the command with sudo

Now test your installation::

> sphinx-build --version
Sphinx (sphinx-build) 1.3.1

For a more detailed installation guide refer to this document

Check out documentation source

Since write acecss to the main documentation repository is restricted you may want to work on your personal fork. Login on Github with your account, navigate to the documentation reposiroty and click on fork. You will be redirected to your own fork of the documentation.

Make sure you already configured your Git username and email address

Now clone your repository locally::

git clone https://github.com/your-user/doc-geonode.git

where your-user is your username on GitHub.

Now make the changes you want to the documentation.

Build the documentation

To build the documentation locally on your machine, open the terminal and move to the project root directory, then run the following::

make html

The html version of the documentation will be build under the build subfolder. Use your favorite web browser to open the index file called index.html.

When you make changes to the documentation re-build it periodically to make sure the end result matches what you expect.

Edit the documentation

The documentation is kept in reStructuredText format. For a quick reference refer to this document. For a more in-depth document refer to the official documentation.

Submit your changes to the main repository

You are done making changes to the documentation and you are ready to submit your changes. If you are new to Git make sure you grasped the basics of it before moving on. There are many sources of information online, you can Google for it or read this introduction.

Run git status and git diff to review the changes you made and re-build the documentation locally as explained above.

Add the files with the changes you want to submit to the staging area:

git add path/to/file

And commit the changes:

git commit

Then push them to your personal GitHub repository:

git push origin master

Open your favorite browser and navigate to your GitHub repository. You will be able to see your latest commit along with a message stating that your branch is ahead of the main repository. Click on the ‘pull request’ button to make a pull request against the official documentation repository.

Create a pull request with a brief description of what you did. The pull request will be reviewed and eventually merged into the official documentation repository.