[docs] Update the documentation

umap-project · Nov 28, 2023 · b3d6d6d · b3d6d6d
1 parent 34ee8e8
commit b3d6d6d
Show file tree

Hide file tree

Showing 11 changed files with 311 additions and 339 deletions.
diff --git a/docs/architecture/frontend.md b/docs/architecture/frontend.md
@@ -0,0 +1,73 @@
+# The frontend
+
+uMap is using Leaflet on the frontend. It's actually extending it: each uMap object extends the ones from Leaflet.
+
+```mermaid
+erDiagram
+    Map ||--o{ DataLayer : datalayers
+    Map{
+	    JSON permissions
+	    JSON metadata
+    }
+    DataLayer ||--o{Feature : data
+    DataLayer {
+	    JSON metadata
+	    JSON permissions
+    }
+```
+
+Here are the important concepts and files:
+
+- `umap.js` contains `Map`, the map object. It's the main entry point, which references all the related properties. It contains metadata, permissions, and data layers.
+- `umap.layer.js` contains `DataLayer`, which contains metadata, permissions, and data.
+- `umap.permissions.js` handles the permissions of the map. There is a different file handling the permissions of the datalayer:
+- `umap.datalayer.permissions.js`.
+
+## Map (`L.U.Map`)
+
+`L.U.Map` is the class that's called by the server templates (in `map_init.html` and `map_fragment.html` used when we display lists of maps, like the homepage).
+
+It contains references to datalayers, and to the controls (the buttons that appears on the map)
+
+To be able to change the way the client behaves, querystring parameters can be used to overload the settings stored in the database. This is useful for instance when using iframes to display the map on a different website.
+
+uMap has an edit mode. If you don't have the rights you cannot save nor edit, you can't edit the permissions as well.
+
+A map contains references to:
+
+- controls
+- datalayers
+
+## DataLayers (`L.U.Datalayer`)
+
+The datalayers contains data, and a layer (a way to represent them).
+
+Each data layer contains a "layer", to know what type of layer it is. It's one of:
+
+- Choropleth (`L.U.Layer.Choropleth`)
+- Cluster (`L.U.Layer.Cluster`)
+- Heat (`L.U.Layer.Heat`)
+
+When the data layers are initialized, they can have two states:
+- `loaded`: the object is loaded in memory. At this stage we have access to all the datalayer's metada (name, type, id)
+- `dataLoaded` : the data is available to be used, so we can for instance compute the center of the map (when it's dynamic).
+
+- `backupOptions` is here to make it possible to cancel what have been done (using undo). It stores the old settings for the data-layer.
+
+## Storage
+
+To mark what needs to be synced with the server, uMap currently mark objects as "dirty". Something marked as "dirty" has changed on the client, but is not yet saved on the server.
+
+Each map, datalayer and permission objects can be marked as "dirty". When a change is made on an object, it will mark its parent as "dirty" as well, so it can be updated accordingly.
+
+### Saving data to the server with `umap.save()`
+
+Here is what's being done when you call `map.save()`:
+
+1. `map.saveSelf()`, posting `name`, `center` and `settings` to the server, and then
+2. calls `permission.save()`, which will post the permissions to the server, and then call back
+3. `map.continueSaving()`, which will take the first dirtyLayer and call
+4. `datalayer.save()` on it. It does the following:
+	1. Post the data (`name`, `displayOnLoad`, `rank`, `settings`, and `geojson`)
+	2. Calls `permission.save()`, posting `edit_status` to the server, and then calling `map.continue_saving()` and remove the datalayer from `dirtyDatalayers`.
+5. When the `dirtyDatalayers` list is empty, we are done.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,92 +1,31 @@
 # Contributing
 
-## Translating
-
-Translation is managed through [Transifex](https://www.transifex.com/openstreetmap/umap/).
-
-## Bug 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
-
-### Environment 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:
+So you want to contribute to uMap? Great news 🙌
 
-```
-# uMap
-export UMAP_SETTINGS=~/.umap/umap.conf
-```
+We've put together this document so you have a brief overview of how things work.
+You can help on different areas: translation, bug triage, documentation and development.
 
-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.
-
-Once you are in the `umap/` folder, create a Python virtual environment:
-
-    python3 -m venv venv
-    source venv/bin/activate
-
-Now, the `umap` command will be available.
-
-*Note: if you close your terminal, you will need to re-run that command from `~/wk/umap`:*
+## Translating
 
-    source venv/bin/activate
+uMap is translated to more than 50 languages! The translation is managed through [Transifex](https://www.transifex.com/openstreetmap/umap/). You will need an account to get started, and then you'll be able to translate easily.
 
-To test your code, you will add to install umap from your git folder. Go to `~/wk/umap` and run:
+## Bug Triage
 
-    make install
+You are very welcome to help us triage [uMap issues](https://github.com/umap-project/umap/issues). Don't hesitate to help other users by answering questions, give your point of view in discussions and just report bugs!
 
-This command will check dependencies and install uMap from sources inside folder.
+## Reporting a bug
 
-When installing from the git repository, do not forget to run `make installjs` and `make vendors`, before running `umap collectstatic` (as mentioned in [Ubuntu from scratch](ubuntu.md)).
+If you've encountered a bug, don't hesitate to tell us about it. The best way to do this is by [opening a ticket on the bug tracker](https://github.com/umap-project/umap/issues/new/choose). But please, first, [have a look around](https://github.com/umap-project/umap/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) to see if other users already reported something 😅
 
-Create a PostgreSQL database and apply migrations to setup your database:
+## Hacking on the code
 
-    createdb umap
-    umap migrate
+Following the [installation instructions](install.md) should get you started to hack on the code.
 
-You should now be able to start your local uMap instance:
+## Merging rules
 
-    umap runserver 0.0.0.0:8000
+Pull requests 
 
-### Update translations
+## Update translations
 
 Install needed tools:
 

diff --git a/docs/custom.md b/docs/custom.md
@@ -1,6 +1,5 @@
 # Customize your uMap installation
 
-
 When running your own uMap, you may want to changed its appearance, for example
 you want your own logo on the home page, or you want to apply some design, or
 you want to add some tracking (but anonymous!) script…

diff --git a/docs/docker.md → docs/deploy/docker.md b/docs/docker.md → docs/deploy/docker.md
@@ -1,11 +1,14 @@
 # Docker
 
-There is now an official [uMap](https://hub.docker.com/r/umap/umap) image.
+## Docker Hub
 
-To run it with docker compose, create a `docker-compose.yml` like this:
+An official [uMap docker image](https://hub.docker.com/r/umap/umap) is available on the docker hub.
 
-_Sample docker-compose.yml_ 
-```yaml
+## Docker compose
+
+If you prefer to run it with docker compose, here is the configuration file:
+
+```yaml title="docker-compose.yml"
 version: '3'
 services:
   db:
@@ -47,16 +50,17 @@ You can use this example below and it will run, but you may want to look at the
 
 Make sure the settings in the docker-compose don't conflict with the sample config and vice-versa. In particular, remove the DATABASES section from the config file if using the docker-compose file, or it will override the DATABASE_URL setting and things won't work. 
 
-_Sample umap.conf_ 
-```python 
-"""                                                                                                                                                                                      
-Example settings for docker quickstart: 
-Lots of stuff has been removed for simplicity                                                                                                                                     
-                                                                                                                                                                                         
-See https://umap-project.readthedocs.io/en/master/settings/                                                                                                                              
-                                                                                                                                                                                         
-Things YOU need to change before launching:                                                                                                                                              
-- modify SECRET_KEY                                                                                                                                                                      
+```python title="umap.conf"
+"""
+Example settings for docker quickstart: lots of stuff has been removed for simplicity.
+
+You can get the whole list of settings at:
+
+  https://umap-project.readthedocs.io/en/master/settings/
+
+Here are the settings YOU HAVE TO CHANGE before launching:
+
+- SECRET_KEY
 """
 
 from umap.settings.base import *   # pylint: disable=W0614,W0401                                                                                                                         
@@ -88,32 +92,15 @@ Some basic settings are available through env vars (see https://github.com/umap-
 but if you need more custom ones (like custom OAuth configuration), the easiest
 way is to put them in a [settings file](settings.md) and mount it to `/etc/umap/umap.conf`.
 
----
-
-#### Quick sidebar about docker and docker-compose
-A multi-platform tutorial on [installing docker](https://docs.docker.com/get-docker/) and docker-compose is outside the scope of this howto, but if you are on a recent Ubuntu, this is all you need to install both:
+### Getting started with docker compose
 
-```bash
-sudo groupadd docker 
-sudo snap install docker
-sudo usermod -aG docker $USER
-# EXIT and log back in to pickup the docker group membership, then test with
-docker run hello-world
-```
-
-Current versions of docker compose are integrated into the docker command and launch with `docker compose` (two words) -- older versions use a separate binary named `docker-compose`. Either one will work for this. 
-
----
+With docker installed on your machine, start the server with 
 
-### Initial launch
-
-Start the server with 
 ```bash
 docker compose up
 ```
-... and let it run some initial setup until the output quiesces with a message about spawning uWSGI workers. Because there is a race between the time the app tries to connect to the DB and when the DB is actually ready, you might see a few exceptions/errors about 'psycopg' being unable to connect. This should sort itself out as the app retries. 
 
-### Create superuser
+... and let it run some initial setup until the output quiesces with a message about spawning uWSGI workers. Because there is a race between the time the app tries to connect to the DB and when the DB is actually ready, you might see a few exceptions/errors about 'psycopg' being unable to connect. This should sort itself out as the app retries. 
 
 Now you need to create your site superuser. Stop the server (Ctrl-C) and then type:
 ```bash
@@ -122,8 +109,6 @@ docker-compose run app /venv/bin/umap createsuperuser
 
 Once that's done, you can relaunch your server with `docker compose up`
 
-### Try It!
-
 You should now be able to browse to your uMap instance from a browser on your local system, by pointing your browser to `https://localhost:8001/` (equivalent to `${SITE_URL}` in the docker-compose file, above).
 
 ### Administration

diff --git a/docs/ubuntu.md → docs/deploy/ubuntu.md b/docs/ubuntu.md → docs/deploy/ubuntu.md
@@ -6,14 +6,20 @@ You need sudo grants on this server, and it must be connected to Internet.
 
 ## Install system dependencies
 
-    sudo apt update
-    sudo apt install python3 python3-dev python3-venv virtualenv wget nginx uwsgi uwsgi-plugin-python3 postgresql gcc postgis libpq-dev
+``` bash
+sudo apt update
+sudo apt install python3 python3-dev python3-venv virtualenv wget nginx uwsgi uwsgi-plugin-python3 postgresql gcc postgis libpq-dev
+``` 
 
-*Note: nginx and uwsgi are not required for local development environment*
+!! note
+
+    Nginx and uwsgi are not required for local development environment.
 
 ## Create deployment directories:
 
-    sudo mkdir -p /etc/umap
+```bash
+sudo mkdir -p /etc/umap
+```
 
 *You can change this path, but then remember to adapt the other steps accordingly.*
 

diff --git a/docs/index.md b/docs/index.md
@@ -1,8 +1,17 @@
 # uMap developer documentation
 
-*This documentation is intended for people aiming to install and configure uMap.
-If you are looking for user documentation, have a look at [the OSM wiki page](http://wiki.openstreetmap.org/wiki/UMap#Tutorials).*
+!!! info "Developer docs"
 
-uMap is a Django project, so in case of doubt always refer to the [Django documentation](https://docs.djangoproject.com).
+    This documentation is intended for people aiming to install and configure uMap.
 
-Now let's start by [installing uMap](install.md)!
+    If you are looking for user documentation, have a look at [the OSM wiki page](http://wiki.openstreetmap.org/wiki/UMap#Tutorials).
+
+uMap lets you create maps with OpenStreetMap layers in a minute, and embed them in your site.
+
+If you want to get started, follow the [installation](install.md) guide.
+
+You might want to:
+
+- See [the developer docs](developer.md)
+- Read [the contributing guidelines](contributing.md)
+- Read through the [deployment tips](deploy/tips.md)