make documentation multilingual (English, Spanish)

Author: Wouter Buytaert

.gitignore

@@ -113,3 +113,4 @@ GitHub.sublime-settings
 _other/
 log/
 scratch/
+.DS_Store

README.md

@@ -17,7 +17,4 @@ A live version of the tool can be found in:
 
 Paricia is developed at [Imperial College London](https://www.imperial.ac.uk/) by the Research Software Engineering team within the Research Computing Group. The project is coordinated by [Prof. Wouter Buytaert](https://www.imperial.ac.uk/people/w.buytaert), who leads a group in the Civil Engineering Department and that focus on the impact of environmental change on the water cycle and its consequences for managing water resources. This work involves gathering and processing time-series data like water level, flow and temperature from various monitoring stations based in mountainous areas such as the Andes and Himalayas.
 
-The code was originally based on the iMHEA platform - Plataforma para la **I**niciativa Regional de **M**onitoreo **H**idrológico de **E**cosistemas **A**ndinos. We are grateful to the following instututions for the development of iMHEA and for sharing their code to use as a starting point for Paricia:
-
-- [Fondo para la Proteccion del Agua (FONAG)](https://www.fonag.org.ec/web/), Ecuador.
-- [Empresa Pública Metropolitana de Agua Potable Y Saneamiento de Quito (EPMAPS)](https://www.aguaquito.gob.ec/home/), Ecuador.
+The code was originally based on the SEDC platform developed by the [Fondo para la Proteccion del Agua (FONAG)](https://www.fonag.org.ec/web/) and the [Empresa Pública Metropolitana de Agua Potable Y Saneamiento de Quito (EPMAPS)](https://www.aguaquito.gob.ec/home/), Ecuador. We are grateful to these institutes for sharing their code to use as a starting point for Paricia:

mkdocs.yml config/en/mkdocs.yml

@@ -1,8 +1,13 @@
-site_name: Paricia
+site_name: Paricia user manual
 repo_url: https://github.com/ImperialCollegeLondon/paricia
 
+docs_dir: '../../docs/en'                           # Where to find the English markdown files
+site_dir: '../../site/en'                      # Where to put the English HTML files
+
 theme:
   name: "material"
+  custom_dir: '../../overrides/'                  # This is where the customization of the theme lives
+  Language: en
   features:
     - navigation.tabs
 
@@ -20,11 +25,27 @@ markdown_extensions:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
+extra_css:
+  - assets/stylesheets/yesplan.css                  # CSS is shared by all languages
+
+extra:                                              # Language Selection
+  alternate:  
+      # Switch to English
+    - name: English
+      link: /en/
+      lang: en
+    # Switch to Spanish
+    - name: Español
+      link: /es/
+      lang: es
+
+
 plugins:
-  - search
+  - search:
+      lang: en                                      # Set language for search
   - gen-files:
       scripts:
-        - docs/gen_ref_nav.py
+        - ../../includes/gen_ref_nav.py
   - literate-nav:
       nav_file: SUMMARY.md
   - section-index
@@ -45,6 +66,7 @@ plugins:
         ignore_classes: ["no-caption"]
 
 nav:
+  - Home: index.md
   - User Guide:
       - Introduction: introduction.md
       - Reports: reports.md

config/es/mkdocs.yml

@@ -0,0 +1,90 @@
+site_name: Manual de Paricia
+repo_url: https://github.com/ImperialCollegeLondon/paricia
+
+docs_dir: '../../docs/es'                           # Where to find the English markdown files
+site_dir: '../../site/es'                      # Where to put the English HTML files
+
+theme:
+  name: "material"
+  custom_dir: '../../overrides/'                  # This is where the customization of the theme lives
+  Language: es
+  features:
+    - navigation.tabs
+
+markdown_extensions:
+  - admonition
+  - pymdownx.snippets:
+      check_paths: true
+  - toc:
+      permalink: "¤"
+  - markdown_include.include:
+      base_path: .
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+extra_css:
+  - assets/stylesheets/yesplan.css                  # CSS is shared by all languages
+
+extra:                                              # Language Selection
+  alternate:  
+      # Switch to English
+    - name: English
+      link: /en/
+      lang: en
+    # Switch to Spanish
+    - name: Español
+      link: /es/
+      lang: es
+
+
+plugins:
+  - search:
+      lang: es                                      # Set language for search
+  - gen-files:
+      scripts:
+        - ../../includes/gen_ref_nav.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
+  - glightbox
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            show_source: true
+            show_root_heading: true
+            show_category_heading: true
+            merge_init_into_class: true
+            members: true
+          paths: [measurement]
+  - caption:
+      figure:
+        ignore_classes: ["no-caption"]
+
+nav:
+  - Guía de usuario:
+      - Introducción: introduction.md
+      - Informes: reports.md
+      - Permisos: permissions.md
+      - Añadir elementos: adding_elements.md
+      - Importar datos: importing_data.md
+      - Validación: validation.md
+  - Guía de desarrollo:
+      - Contribuyendo: contributing.md
+      - Instalación: installation.md
+      - Control de calidad: quality_assurance.md
+      - Datos sinteticos: synthetic_data.md
+      - Administradores: admin.md
+      - Estructura del código:
+          - Índice: Applications/index.md
+          - Formatear: Applications/formatting.md
+          - Variables: Applications/variable.md
+          - Sensores: Applications/sensor.md
+          - Estationes: Applications/station.md
+          - Mediciones: Applications/measurement.md
+          - Importación: Applications/importing.md
+      - API Reference: reference/

docs/Applications/formatting.md docs/en/Applications/formatting.md

@@ -6,11 +6,11 @@ All elements that can be created in Paricia - except for the data import, which
 
 - Choose the element of interest from the submenu in the top bar, e.g. `Variable` within the `Variables` menu.
 
-![Selecting a element from the top menu](images/selecting_component.png)
+![Selecting a element from the top menu](../assets/images/selecting_component.png)
 
 - The page now displays the list of existing elements of that type that the user can view - i.e., those that are public or that are their own. You can sort the entries clicking on the column names or filter them to select just some entries.
 
-![List of variables a user can view](images/variables_list.png)
+![List of variables a user can view](../assets/images/variables_list.png)
 
 - Clicking on an existing element ID allows to view the details of that element and to edit it, if the user has permission to do so.
 - Clicking on the `New` button at the top allows to create a new element of that type.
@@ -21,7 +21,7 @@ Some elements are very simple and have just one or two fields to complete. Other
 
 Let's take the variables creation form as an example.
 
-![Form used to create a new variable](images/variable_creation.png)
+![Form used to create a new variable](../assets/images/variable_creation.png)
 
 As we can see in this form, there is a field called `Visibility`. All elements have this field and it defines who else can see the details and use the element to define their own elements.
 

docs/Applications/images/formatting.png docs/en/Applications/images/formatting.png

@@ -6,7 +6,7 @@ There are two ways of becoming an Admin user
 
 1. Asking another Admin to give superuser permissions to that user. This is done via the Paricia Admin. Within the `Users` app, select the user whose permissions need changing and check the box granting the user `Superuser status`, as shown in this picture:
 
-![Checking the third box grants the user all Paricia permissions](images/superuser.png)
+![Checking the third box grants the user all Paricia permissions](../assets/images/superuser.png)
 
 2. Via the command line. This is a more advanced method and typically required only when setting up Paricia for the first time, either locally for development or in a new server. We will assume that that Paricia has been launched using `docker compose`, as instructed in the [installation instructions](./installation.md#docker-deployment). The steps in this case are:
 

docs/Applications/images/measurement.png docs/en/Applications/images/measurement.png

@@ -6,11 +6,11 @@ The whole reason for Paricia to exist is to store and facilitate access to hydro
 
 Data import is done via Paricia import listing, clicking in the `New` button at the top of the page.
 
-![Data import list](images/import_list.png)
+![Data import list](../assets/images/import_list.png)
 
 A form will open in a new page, containing several fields to be filled by the users.
 
-![Form to import new data](images/importing_add_data.png)
+![Form to import new data](../assets/images/importing_add_data.png)
 
 ### Format
 
@@ -20,7 +20,7 @@ The **Format** is the most important option to choose. If the format is not corr
 
 The following figure shows the classifications available for a particular format:
 
-![List of variables classification into columns](images/classifications.png)
+![List of variables classification into columns](../assets/images/classifications.png)
 
 Clicking in each classification `id` will show you more information about that particular classification. Keep in mind you might not have permission to see the details of that classification.
 
@@ -36,18 +36,18 @@ Once the form is complete, click `Save` at the top of the page and the import pr
 
 - **Not Queued**: The data ingestion has not started, yet.
 
-![Data ingestion not queued](images/importing_not_queued.png)
+![Data ingestion not queued](../assets/images/importing_not_queued.png)
 
 - **Queued**: The data ingestion has started. Data file has been opened and is being processed.
 
-![Data ingestion queued](images/importing_queued.png)
+![Data ingestion queued](../assets/images/importing_queued.png)
 
 - **Completed**: The data ingestion has completed successfully. Information on the start and end dates of the data **in the local timezone of the user**, as well as the number of records, will appear updated
 
-![Data ingestion completed](images/importing_completed.png)
+![Data ingestion completed](../assets/images/importing_completed.png)
 
 - **Failed**: The data ingestion failed. Information on what went wrong should appear in the log box at the bottom of the data import detail. Try to fix the issues, based on the feedback provided, check the box `Reprocess Data`, and save the form again to trigger another data ingestion process.
 
-![Data ingestion failed](images/importing_failed.png)
+![Data ingestion failed](../assets/images/importing_failed.png)
 
 Once the data has been ingested successfully, it will be available to validate in the [Validation screen](validation.md) and in the Report screen, if the Station it belongs to is labelled as public or internal.

docs/Applications/images/sensor.png docs/en/Applications/images/sensor.png

@@ -36,11 +36,17 @@ python -m pip install -r requirements-dev.txt
 python -m pip install -r requirements-doc.txt
 ```
 
+Then, paricia itself can be installed with:
+
+```
+python -m pip install -e .
+```
+
 That should be it. The virtual environment should be ready for the development of Paricia and its documentation. Just indicate your code editor which environment you are using in case it does not pick it automatically.
 
 !!! warning "Running Paricia and tests"
 
-    You will not be able to run Paricia itself or the tests from the virtual environment as a TimescaleDB is required for that, which we have not installed. See the [docker deployment](#docker-deployment) section to learn how to do that.
+    You will not be able to run Paricia itself or the tests from the virtual environment because this requires TimescaleDB, which is not installed as part of the virtual environment. See the [docker deployment](#docker-deployment) section to learn how to do that.
 
 ## Docker deployment
 
@@ -72,18 +78,22 @@ Unless you destroy the docker volume containing the database or manually flush i
 
 The documentation uses [`mkdocs`](https://www.mkdocs.org/). This should have been installed alongside all the other doc-related dependencies if you run `python -m pip install -r requirements-doc.txt`, as described above. There's no need to use `docker` to build the documentation locally.
 
-To test the documentation live and have it rebuilt automatically while you edit the documentation files, run:
+Because of the multilingual nature of the documentation, the normal way to serve the documentation (via the commands 'mkdocs build' and 'mkdocs serve') will not work here. Instead you need to use the following commands to build the documentation:
 
 ```
-mkdocs serve -a localhost:8001
+mkdocs build -f config/en/mkdocs.yml
+mkdocs build -f config/es/mkdocs.yml
 ```
 
-The reason for explicitly using `localhost:8001` is because port `8000`, the default, will likely be already in use by Paricia web application.
-
-To build the documentation as standalone html files and related resources, run instead:
+The documentation is now available in the sites/ folder. From there, you can serve it with the python http server:
 
 ```
-mkdocs build
+cd sites/
+python3 -m http.server 8001
 ```
 
-A new directory in the root of the project called `site` would have been created with all the files instead. Open `index.html` in the browser to check this documentation.
+The documentation site can now be accessed via a web browser on http://localhost:8001
+
+
+The reason for explicitly using `localhost:8001` is because port `8000`, the default, will likely be already in use by Paricia web application.
+

docs/Applications/images/station.png docs/en/Applications/images/station.png

@@ -4,7 +4,7 @@ Paricia exposes the data it contains via the **Reports** page.
 
 This page contains a form on the left hand side and a plot on the right, which will display the data selected in the form. No data is displayed in the plot when accessing the page.
 
-![Form to complete in the report page](images/reports_form.png)
+![Form to complete in the report page](../assets/images/reports_form.png)
 
 ## Report types
 
@@ -18,7 +18,7 @@ There are 5 types of reports that can be selected:
 
 All data will have a raw measurements report, but the others will be available only ifthe data has been validated.
 
-## Stations, variables and date range
+## Stations, variables, and date range
 
 The user will only be able to select stations that they can view, meaning that users that are **not logged will see only stations that are public**. Register users will see **public and internal stations**, as well as their own, if any. Check the [Permissions](./permissions.md) for more details on the permissions of each user.
 
@@ -34,15 +34,15 @@ The user can zoom in, selecting the region of interest, and finer data will be s
 
 The following figure shows the ambient temperature in a period of a few weeks. The title indicates an aggregation level of around 23 minutes, meaning that data points displayed are separated 23 minutes on average. Mind that **no processing is done in the data** - no average or other manipulation - simply a selection of existing data points are plotted across the whole range. In other words, if the original data separation was 5 min, then an aggregation level of 23 min means that only 1 point in 4 or 5 is plotted.
 
-![Plot with 23.6 min data aggregation](images/high_aggregation.png)
+![Plot with 23.6 min data aggregation](../assets/images/high_aggregation.png)
 
 In the next plot, we have zoomed in a little bit and now the average separation is 15 min.
 
-![Plot with 15 min data aggregation](images/some_aggregation.png)
+![Plot with 15 min data aggregation](../assets/images/some_aggregation.png)
 
 In the final plot, the zoom is high enough such that no aggregation is required.
 
-![Plot with no data aggregation](images/no_aggregation.png)
+![Plot with no data aggregation](../assets/images/no_aggregation.png)
 
 In all cases, to go back to the full range, either use the tools in the top right corner of the plot or double click on it.
 
@@ -52,4 +52,4 @@ The chosen approach for selecting the data to plot - just skipping points - is e
 
 For example, if we zoom in the first part of the series, we can see some - most likely wrong - data points shooting up to 50. These were not visible in the general view.
 
-![Plot with spikes when there's enough zoom](images/spikes.png)
+![Plot with spikes when there's enough zoom](../assets/images/spikes.png)