Permalink
Switch branches/tags
debian/2.10.0+rc4 debian/2.10.0+rc3 debian/2.10.0+rc2 debian/2.10.0+rc1 debian/2.10.0+rc0 debian/2.8.1+rc0 debian/2.8.0+thefinal0 debian/2.8.0+rc13 debian/2.8.0+rc12 debian/2.8.0+rc11 debian/2.8.0+rc10 debian/2.8.0+rc9 debian/2.8.0+rc8 debian/2.8.0+rc7 debian/2.8.0+rc6 debian/2.8.0+rc5 debian/2.8.0+rc4 debian/2.8.0+rc3 debian/2.8.0+rc2 debian/2.8.0+rc1 debian/2.8.0+rc0 debian/2.7.5+dev20180124154147 debian/2.7.5+dev20180123112419 debian/2.7.4+dev20171114153121 debian/2.7.2+dev20171013181704 debian/2.7.1+dev20171013111656 debian/2.7.0+thefinal0 debian/2.6.3+thefinal0 debian/2.6.2+thefinal0 debian/2.6.1+thefinal0 debian/2.6.0+thefinal0 debian/2.6.0+rc1 debian/2.6.0+beta1 debian/2.6.0+alpha1 debian/2.5.15+thefinal0 debian/2.5.14+thefinal0 debian/2.5.13+thefinal0 debian/2.5.12+thefinal0 debian/2.5.11+thefinal0 debian/2.5.10+thefinal0 debian/2.5.9+thefinal5 debian/2.5.9+thefinal4 debian/2.5.9+thefinal3 debian/2.5.9+thefinal2 debian/2.5.9+thefinal1 debian/2.5.9+thefinal0 debian/2.5.9+dev20170116091118 debian/2.5.7+thefinal0 debian/2.5.6+thefinal0 debian/2.5.5+thefinal0 debian/2.5.4+thefinal0 debian/2.5.3+thefinal0 debian/2.5.2+thefinal0 debian/2.5.1+thefinal0 debian/2.5.0+thefinal0 debian/2.4.1+thefinal1 debian/2.4.0+thefinal0 debian/2.4.0+rc4 debian/2.4.0+rc3 debian/2.4.0+rc2 debian/2.4.0+rc1 debian/2.4.0+dev20141024171719 debian/2.4.0+beta28 debian/2.4.0+beta27 debian/2.4.0+beta26 debian/2.4.0+beta25 debian/2.4.0+beta24 debian/2.4.0+beta23 debian/2.4.0+beta22 debian/2.4.0+beta21 debian/2.4.0+beta20 debian/2.4.0+beta19 debian/2.4.0+beta18 debian/2.4.0+beta17 debian/2.4.0+beta16 debian/2.4.0+beta15 debian/2.4.0+beta14 debian/2.4.0+beta13 debian/2.4.0+beta12 debian/2.4.0+beta11 debian/2.4.0+beta10 debian/2.4.0+beta9 debian/2.4.0+beta8 debian/2.4.0+beta7 debian/2.4.0+beta6 debian/2.4.0+beta5 debian/2.4.0+beta4 debian/2.4.0+beta3 debian/2.4.0+beta2 debian/2.4.0+beta1 debian/2.4.0+alpha38 debian/2.4.0+alpha37 debian/2.4.0+alpha36 debian/2.4.0+alpha35 debian/2.4.0+alpha34 debian/2.4.0+alpha33 debian/2.4.0+alpha32 debian/2.4.0+alpha31 debian/2.4.0+alpha30 debian/2.4.0+alpha29
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
205 lines (115 sloc) 8.94 KB
.. _contrib_docu:
============================================
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 <https://github.com>`_, 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:
.. image:: 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.
.. image:: 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.
.. image:: 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.
.. image:: 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.
.. image:: 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
.. image:: img/create_file.png
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.
.. image:: 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.
.. image:: img/pull_request.PNG