How to contribute to GeoNode’s Documentation¶

If you feel like adding or changing something in the GeoNode documentation you are very welcome to do so. The documentation always needs improvement as the development of the software is going quite fast.

In order to contribute to the GeoNode documentation you should:

Create an account on GitHub
Fork the GeoNode repository
Edit the files in the /docs directory
Submit pull requests

All these things can generally be done on the web, you won’t need to download anything. But if you want to add images to the documentation you will have to do some more initial steps, because this can’t be done on the web. To learn about how images can be added to your documentation and which additional steps have to be done, read the section Add images.

The general steps are explained in more detail below.

Create an account on GitHub¶

The first step is to create an account on GitHub. Just go to Github, find a username that suits you, enter your email and a password and hit Sign up for GitHub. Now you’ve signed in, you can type geonode into the searching area at the top of the website. On top of the search results you will find the repository GeoNode/geonode. By clicking on it you will be entering the repository and will be able to see all the folders and files that are needed for GeoNode. The files needed for the documentation can be found in /docs.

Fork a repository¶

In order to make changes to these files, you first have to fork the repository. On the top of the website you can see the following buttons:

organizational/contribute/img/fork_repo.PNG

Click on the button Fork at the top right and the geonode repository will be forked. You should now be able to see your repository your_name/geonode. If you want to read more about how to fork a repository go to https://help.github.com/articles/fork-a-repo.

Edit files¶

To make some changes to already exiting files or to create new files, go to your GitHub account. Under repositories you will find the geonode repository that you have forked. Click on it and you will again see all the folders and files GeoNode needs.

organizational/contribute/img/repository_geonode.PNG

Click on the folder docs and search for the file that you want to edit. If you found it, click on it and you will be able to see the content of this file.

organizational/contribute/img/index_txt.PNG

To make changes to this file, hit the button edit on the right top. You can now make your changes or add something to the existing content.

organizational/contribute/img/index_edit.PNG

As you can see now, the documentation is written in reStructeredText, a lightweight markup language. To learn how to use it you should read the documentation that can be found here http://docutils.sourceforge.net/docs/user/rst/quickref.html. By hitting the preview button you will be able to see how your text it is going to look like on the web. To save your changes, click on Commit Changes at the bottom of the site. Now you’ve saved the changes in your repository, but the original geonode repository still doesn’t know anything about that! In order to tell them that you have made some changes you have to send a pull request (as described below).

To see your modifications for validation purpose just make sure you installed sphinx tools as:

pip install sphinx
pip install sphinx_rtd_theme

Just go to the docs subdirectory and use the make command with the html option, after you can open the result in your browser as:

cd [yourpath]/geonode/docs
make html
#you can open the index.html in _build subdirectory

Create a new branch

If you are planning bigger changes on the structure of the documentation it is recommended to create a new branch and make your edits here. A new branch can be created by clicking on the button branch: master as shown here.

organizational/contribute/img/create_branch_example.PNG

Just type the name of your new branch, hit enter and your branch will be created. To learn more about branches it is recommended to take a look here https://git-scm.com/book/en/Git-Branching-What-a-Branch-Is.

Note

Before you start editing make sure that you are in the right branch!

Create a new folder/file

If you want to add a completely new issue to the documentation, you have to create a new file (and maybe even folder). As you will see there is no possibility to create an empty folder. You always have to create a new file as well! This can be done here

If you click on create new file here you can first change into another folder by typing the foldername followed by /. If this folder doesn’t exist until now, one will be created. To create a new file in this folder just type filename.txt into the box and hit enter. A short example on how to manage this is given here http://i.stack.imgur.com/n3Wg3.gif.

organizational/contribute/img/create_file_test.PNG

Now a black box will appear where you can add your comments. To save the file, hit the green Commit New File button at the bottom.

Add images¶

This section is about adding images to your documentation. Providing that you’ve read and done the steps described above you can now follow those further steps.

Install and set up Git

To add images to your documentation you have to get your repository onto your local machine. So far you only had your repository on the web. To be able to work on your local machine as well, you have to install git. To do so, type:

sudo apt-get install git

(Usually git has already been installed during geonode installation)

Before you go further you should do some setup steps (can be found here: https://help.github.com/articles/set-up-git).

Clone repository

We assume you have already forked the geonode repository. If not, please do so following _link and return back if ready.

Until now your repository only exists on the web! To get your forked repository on to your machine, you have to clone it. To do so, open a terminal, go to the folder where you want the project to be and type:

git clone https://github.com/your_username/geonode.git my_geonode

Now change the active directory to the newly cloned geonode directory using:

cd my_geonode

To keep track of the original repository (the geonode repository where you forked from), you need to add a remote named upstream. Therefore type:

git remote add upstream https://github.com/GeoNode/geonode.git

By typing:

git fetch upstream

Changes not present in your local repository will be pulled in without modifying your files.

Add folder with images

Warning

If you’ve already made some changes and commits to your repository on the web (during cloning the repository and now), you have to update your repository on the local machine!

Therefore you have to run the following commands:

git fetch origin

git merge

Or instead you could use:

git pull

Your repository should now be up to date! For more information on those commands go to https://git-scm.com/docs.

Note

If you’ve created a new branch, and you want to add the new folder to this branch, make sure you are working on this branch!

Typing:

git status

will show you the current branch. To change this you have to run this command (your_branch is the name of the branch you want to change in):

git checkout your_branch

Now you can easily add a new folder containing images to your repository. Go to the repository on your local machine and decide where you want your new folder containing the images to be (e.g in docs_example). There create a new folder (e.g. images) and add the images manually. Once you’ve done this, open a terminal and direct to to the folder docs_example. To add the folder images including all content to the repository, type:

git add images

If this command doesn’t work, check your path, maybe it is incorrect!

Remark: In order to commit and push the folder, it must not be empty!

The next step is to commit the folder/files:

git commit -m 'Message'

Instead of ‘Message’ write something like ‘add images’. To push the files to the repository type:

git push

Now you are able to see the folder on the web as well!

Include images

To include the images in to your documentation, you have to add the following lines to your file:

.. image:: images/test_img.png

Note

Be aware that everytime you commit something on the web, you have to make git pull on your machine, to keep it up to date!

Pull Request¶

If you are done with your changes, you can send a pull request. This means, that you let the core developers know that you have done some changes and you would like them to review. They can hit accept and your changes will go in to the main line. The pull request can be found here.