Improve documentation (#746)

Add docs: setup a dev environment and server administration

docs/administration.md

@@ -0,0 +1,53 @@
+# Administration
+
+You can access uMap administration page by navigating to `https://your.server.org/admin`
+
+You will have to connect with the admin account created during installation. Default admin username is "umap".
+
+## Icons
+
+Icons (aka pictograms in uMap sources) can be used in your map markers.
+
+Icons are not embedded in uMap sources, you will have to add them manually. So you can choose which icons you want to use.
+
+Example of icons libraries you may want to use:
+
+- [Maki Icons](https://labs.mapbox.com/maki-icons/) (icon set made for map designers)
+- [Osmic Icons](https://gitlab.com/gmgeo/osmic)
+- [SJJB Icons](http://www.sjjb.co.uk/mapicons/contactsheet)
+
+### Import icons manually
+
+You can import icons manually by going to your uMap admin page: `https://your.server.org/admin`
+
+### Import icons automatically
+
+To import icons on your uMap server, you will need to use command `umap import_pictograms`
+
+Note, you can get help with `umap import_pictograms -h`
+
+In this example, we will import Maki icons.
+
+First, we download icons from main site. Inside the downloaded archive, we keep only the icons folder that contains svg files. Place this folder on your server.
+
+Go inside icons folder and remove tiny icons: `rm *-11.svg`
+
+Now, we will use imagemagick to convert svg to png.
+
+`for file in *.svg; do convert -background none $file ${file%15.svg}24.png; done`
+
+To have white icons use:
+`for file in *.svg; do convert -background none -fuzz 100% -fill white -opaque black $file ${file%15.svg}24.png; done`
+
+
+Notes:
+- you may also want to resize image with option `-resize 24x`
+- this solution is not optimal, generated png are blurry.
+
+This will convert the svg to png and rename them from `*-15.svg` to `*-24.png`
+
+Now we will import icons. Note: icons names must end with `-24.png`
+
+`umap import_pictograms --attribution "Maki Icons by Mapbox" icons`
+
+Done. Icons are imported.

docs/contributing.md

@@ -3,3 +3,94 @@
 ## Translating
 
 Translation is managed through [Transifex](https://www.transifex.com/openstreetmap/umap/).
+
+## Bugs Triaging
+
+You are very welcome to help us triaging [uMap issues](https://github.com/umap-project/umap/issues).
+
+* Help other users by answering questions
+* Give your point of view in discussions
+* And so on...
+
+## Development on Ubuntu
+
+### Environnement setup
+
+Choose one of the following two config:
+
+#### Config global to your desktop
+
+Follow the procedure [Ubuntu from scratch](ubuntu.md)
+
+But instead using folders /etc/umap, you can create a ~/.umap folder.
+This folder will contain the umap.conf file.
+
+And for folder /srv/umap, you can create a ~/umap folder (We will remove this folder later)
+
+You will have to set an env var, we will set it in your .bashrc:
+
+    nano ~/.bashrc
+
+Add the following at the end of file:
+
+```
+# uMap
+export UMAP_SETTINGS=~/.umap/umap.conf
+```
+
+Then refresh your terminal
+
+    source ~/.bashrc
+
+Run your local uMap and check that it is working properly.
+
+#### Config inside your local git repo
+
+Follow the procedure [Ubuntu from scratch](ubuntu.md)
+
+You can use the local.py.sample in the git repo and copy it to your local git repo to umap/settings/local.py
+
+See [Installation](install.md)
+
+### Hacking on the code
+
+Create a workspace folder ~/wk and go into it.
+
+"git clone" the main repository and go in the umap folder
+
+Several commands, needs you to be in a virtualenv:
+
+    virtualenv ~/wk/umap/venv --python=/usr/bin/python3.6
+    source ~/wk/umap/venv/bin/activate
+
+Now, command "umap" will be available
+
+*Note: if you close your terminal, you will need to re-run command:*
+
+    source /srv/umap/venv/bin/activate
+
+To test your code, you will add to install umap from your git folder. Go to ~/wk/umap and run:
+
+    pip install -e .
+    # or pip install -e ~/wk/umap
+
+This command, will check dependencies and install uMap from sources inside folder.
+
+To start your local uMap:
+
+    umap runserver 0.0.0.0:8000
+
+### Update translations
+
+Install needed tools:
+
+    apt install gettext transifex-client
+
+Pull the translations from transifex website:
+
+    tx pull -f
+
+Then you will need to update binary files with command:
+    make compilemessages
+
+Done. You can now review and commit modified/added files.

docs/install.md

@@ -1,5 +1,7 @@
 # Installation
 
+*Note: for Ubuntu follow procedure [Ubuntu from scratch](ubuntu.md)*
+
 Create a geo aware database. See [Geodjango doc](https://docs.djangoproject.com/en/dev/ref/contrib/gis/install/) for backend installation.
 
 Create a virtual environment

docs/ubuntu.md

@@ -6,8 +6,9 @@ You need sudo grants on this server, and it must be connected to Internet.
 
 ## Install system dependencies
 
-    sudo apt install build-essential autoconf python3.5 python3.5-dev python-virtualenv wget nginx uwsgi uwsgi-plugin-python3 postgresql-9.5 postgresql-server-dev-9.5 postgresql-9.5-postgis-2.2 git libxml2-dev libxslt1-dev zlib1g-dev
+    sudo apt install build-essential autoconf python3.6 python3.6-dev python-virtualenv wget nginx uwsgi uwsgi-plugin-python3 postgresql-9.5 postgresql-server-dev-9.5 postgresql-9.5-postgis-2.2 git libxml2-dev libxslt1-dev zlib1g-dev
 
+*Note: nginx and uwsgi are not required for local development environment*
 
 *Note: uMap also works with python 2.7 and 3.4, so adapt the package names if you work with another version.*
 
@@ -58,7 +59,7 @@ From now on, unless we say differently, the commands are run as `umap` user.
 
 ## Create a virtualenv and activate it
 
-    virtualenv /srv/umap/venv --python=/usr/bin/python3.5
+    virtualenv /srv/umap/venv --python=/usr/bin/python3.6
     source /srv/umap/venv/bin/activate
 
 *Note: this activation is not persistent, so if you open a new terminal window,
@@ -74,6 +75,16 @@ you will need to run again this last line.*
 
     wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O /etc/umap/umap.conf
 
+## Customize umap.conf
+
+    nano /etc/umap/umap.conf
+
+Change the following properties:
+
+```
+STATIC_ROOT = '/srv/umap/var/static'
+MEDIA_ROOT = '/srv/umap/var/data'
+```
 
 ## Create the tables
 

mkdocs.yml

@@ -2,6 +2,7 @@ site_name: uMap
 pages:
 - Home: index.md
 - Installation: install.md
+- Administration: administration.md
 - Contributing: contributing.md
 - how-tos:
   - Ubuntu from scratch: ubuntu.md