diff --git a/Dockerfile b/Dockerfile
index 34996bb76d14e8157cbd0677b70fbdef618e1685..e29fde34b0e4887255d8ac49ac6f64ed9b3b345e 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -4,11 +4,14 @@ FROM python:3.6.8-alpine3.9 as builder
# Set build directory
WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
# add the current directory to the container as /app
ADD . /app
# Perform build and cleanup artifacts
-RUN pip install mkdocs && pip install mkdocs-material && pip install plantuml-markdown
+# RUN pip install mkdocs && pip install mkdocs-material && pip install plantuml-markdown
# build the documentation site
RUN mkdocs build
diff --git a/docs/features/admin-tools.md b/docs/administration/admin-tools.md
similarity index 100%
rename from docs/features/admin-tools.md
rename to docs/administration/admin-tools.md
diff --git a/docs/features/api-gateway.md b/docs/architecture/index.md
similarity index 100%
rename from docs/features/api-gateway.md
rename to docs/architecture/index.md
diff --git a/docs/features/monitoring.md b/docs/components/indexers/editorial-content.md
similarity index 100%
rename from docs/features/monitoring.md
rename to docs/components/indexers/editorial-content.md
diff --git a/docs/features/services/csv-catalog-downloader.md b/docs/components/indexers/metadata-and-data.md
similarity index 100%
rename from docs/features/services/csv-catalog-downloader.md
rename to docs/components/indexers/metadata-and-data.md
diff --git a/docs/features/services/elasticsearch/elasticsearch.md b/docs/components/off-the-shelf-apps/api-gateway.md
similarity index 100%
rename from docs/features/services/elasticsearch/elasticsearch.md
rename to docs/components/off-the-shelf-apps/api-gateway.md
diff --git a/docs/features/cms.md b/docs/components/off-the-shelf-apps/cms.md
similarity index 100%
rename from docs/features/cms.md
rename to docs/components/off-the-shelf-apps/cms.md
diff --git a/docs/features/services/elasticsearch/indexer.md b/docs/components/off-the-shelf-apps/elasticsearch.md
similarity index 100%
rename from docs/features/services/elasticsearch/indexer.md
rename to docs/components/off-the-shelf-apps/elasticsearch.md
diff --git a/docs/features/services/authentication.md b/docs/components/services/authentication.md
similarity index 100%
rename from docs/features/services/authentication.md
rename to docs/components/services/authentication.md
diff --git a/docs/components/services/csv-catalog-downloader.md b/docs/components/services/csv-catalog-downloader.md
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/docs/features/services/legacy-auth-middleware.md b/docs/components/services/legacy-auth-middleware.md
similarity index 100%
rename from docs/features/services/legacy-auth-middleware.md
rename to docs/components/services/legacy-auth-middleware.md
diff --git a/docs/features/services/mail.md b/docs/components/services/mail.md
similarity index 100%
rename from docs/features/services/mail.md
rename to docs/components/services/mail.md
diff --git a/docs/features/services/media-library.md b/docs/components/services/media-library.md
similarity index 100%
rename from docs/features/services/media-library.md
rename to docs/components/services/media-library.md
diff --git a/docs/features/services/organizations.md b/docs/components/services/organizations.md
similarity index 100%
rename from docs/features/services/organizations.md
rename to docs/components/services/organizations.md
diff --git a/docs/features/services/resources.md b/docs/components/services/resources.md
similarity index 100%
rename from docs/features/services/resources.md
rename to docs/components/services/resources.md
diff --git a/docs/features/admin-gui.md b/docs/components/specific-apps/admin-gui.md
similarity index 100%
rename from docs/features/admin-gui.md
rename to docs/components/specific-apps/admin-gui.md
diff --git a/docs/features/web-app.md b/docs/components/specific-apps/web-app.md
similarity index 100%
rename from docs/features/web-app.md
rename to docs/components/specific-apps/web-app.md
diff --git a/docs/monitoring/monitoring.md b/docs/monitoring/monitoring.md
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/docs/overview/index.md b/docs/overview/index.md
index c0e65ce57d08b6aee95bad9f1f9729c2d31986e6..2dfabe2ad655145eae67374ce5939f245eff54e1 100644
--- a/docs/overview/index.md
+++ b/docs/overview/index.md
@@ -1,6 +1,6 @@
# Overview
-data.grandlyon.com is a web platform developed by the Métropole de Lyon, aiming at facilitating and promoting the sharing of (open) data provided by public and private actors of the Lyon metropolitan area.
+data.grandlyon.com is a web platform owned by the Métropole de Lyon, aiming at facilitating and promoting the sharing of (open) data provided by public and private actors of the Lyon metropolitan area.
data.grandlyon.com consists of two macro-components, a Web Portal and a Core:
@@ -14,12 +14,11 @@ package "data.grandlyon.com" {
@enduml
```
-In this respect, the Web Portal is just one of the various Core's clients, together with 3rd-party client applications:
+In this respect, the Web Portal is just one of the various Core's clients, in the same way as 3rd-party client applications:
```plantuml
@startuml
-
package "3rd-party Client Application" {
[Some Component]
}
@@ -33,20 +32,27 @@ package "data.grandlyon.com" {
@enduml
```
-This project concerns the **Web Portal** component only.
+**This development project concerns the Web Portal component only.**
# Main features
-The data.grandlyon.com's Web Portal includes the following main features, oriented towards its end-users:
+The data.grandlyon.com's Web Portal includes the following main features:
+
+Concerned entity | ID - Description | Users
+--- | --- | ---
+Datasets | F1 - Presenting metadata (title, description, terms, ...) <br> F2 - Showing tabular views of data (if applicable) <br> F3 - Showing map views of data (if applicable) <br> F4 - Showing linked resources (APIs, files) <br> F5 - Performing full-text searches against data and metadata <br> F6 - Performing faceted searches against metadata <br> F7 - Composing custom queries against the Core APIs | end-users
+Users | F8 - Creating/updating/deleting accounts <br> F9 - Performing logins and logouts <br> F10 - Gaining access to restricted-access resources <br> | end-users
+Editorial Content | F11 - Editing static pages (approach, terms of use, ...) <br> F12 - Displaying static pages (approach, terms of use, ...) <br> F13 - Editing articles <br> F14 - Displaying articles <br> F15 - Editing the catalog of partners (data producers, ...) <br> F16 - Displaying the catalog of partners (data producers, ...) <br> F17 - Editing the catalog of data reuses (applications, websites, articles, ...) <br> F18 - Displaying the catalog of data reuses (applications, websites, articles, ...) <br> F19 - Editing the catalog of the Open Source initiatives powering this project <br> F20 - Displaying the catalog of the Open Source initiatives powering this project | back-office <br> end-users <br> back-office <br> end-users <br> back-office <br> end-users <br> back-office <br> end-users <br> back-office <br> end-users
+Support | F21 - Allowing users to contact the user support | end-users
-* it showcases the datasets hosted by the Core component, presenting:
+<!-- * it showcases the datasets hosted by the Core component, presenting:
* metadata (title, description, terms, ...)
* tabular view (if applicable)
* map view (if applicable)
* linked resources (APIs, files)
* it allows users to
* perform full-text searches within data and metadata
- * create account, establish authenticated sessions
+ * create accounts, establish authenticated sessions
* gain access to restricted-access datasets
* compose custom queries against the Core APIs
* contact the user support, provide feedback
@@ -56,7 +62,7 @@ The data.grandlyon.com's Web Portal includes the following main features, orient
* catalogs of
* partners (data producers, ...)
* reuses of data (applications, websites, articles, ...)
- * Open Source software the project relies on
+ * Open Source software the project relies on -->
The data.grandlyon.com's Web Portal also features an independent GUI allowing the back-office users to administer the editorial content.
@@ -65,18 +71,20 @@ The data.grandlyon.com's Web Portal also features an independent GUI allowing th
...an overview...
+# Components
+
## Core components
-In alphabetical order:
+The following table lists, in alphabetical order, the components of data.grandlyon.com's Core macro-component that are used by the Web Portal:
ID | Name | Type | Website | Usage
--- | --- | --- | --- | ---
C1 | Legacy AUTH | specific | | AUTHN/AUTHZ service
C2 | PostgreSQL + PostGIS | off-the-shelf | [Link](https://postgis.net/) | Data Source
C3 | GeoNetwork | off-the-shelf | [Link](https://www.geonetwork-opensource.org/) | Metadata Catalog
-C4 | MapServer | off-the-shelf | [Link](https://mapserver.org/) | WMS Server
+C4 | MapServer | off-the-shelf | [Link](https://mapserver.org/) | WMS and MVT Server
-The latter components are provided by the Core macro-component of the data.grandlyon.com platform, therefore they are beyond the scope of this development project.
+The latter components being provided by the Core macro-component of the data.grandlyon.com platform, their development is beyond the scope of this project.
<!-- Notes:
* The component C1 is deemed as "legacy" because... -->
@@ -88,8 +96,9 @@ ID | Name | Website | Usage
A1 | Elasticsearch | [Link](https://www.elastic.co/fr/products/elasticsearch) | Search Engine
A2 | Ghost | [Link](https://ghost.org/) | Headless CMS
A3 | Kong | [Link](https://konghq.com/kong/) | API Gateway
-A4 | MinIO | [Link](https://min.io/) | Object Store
-A5 | Postfix | [Link](http://www.postfix.org/) | SMTP Server
+A4 | Matomo | [Link](https://matomo.org/) | Web Analytics
+A5 | MinIO | [Link](https://min.io/) | Object Store
+A6 | Postfix | [Link](http://www.postfix.org/) | SMTP Server
@@ -97,22 +106,24 @@ A5 | Postfix | [Link](http://www.postfix.org/) | SMTP Server
ID | Name | Repo | Doc | Usage | Deps
--- | --- | --- | --- | --- | ---
-M1 | Legacy AUTH | ... | ... | user services, | C1
+M1 | Legacy AUTH | ... | ... | Facilitating the interaction between the Web Portal Authentication Service (S1) and the AUTHN/AUTHZ Service (C1) hosted by data.grandlyon.com's Core macro-component | C1
## Proxies
ID | Name | Repo | Doc | Usage | Deps
--- | --- | --- | --- | --- | ---
-P1 | Map Proxy | ... | ... | ... | C5
+P1 | Map Proxy | ... | ... | Proxying requests that the Web Portal performs against the cartographic Web Services (WMS, MVT) hosted by data.grandlyon.com's Core macro-component| C4
## Indexers
+The following custom indexers are used to index documents in Elasticsearch (A1) in order to make them full-text searchable.
+
ID | Name | Repo | Doc | Usage | Deps
--- | --- | --- | --- | --- | ---
-I1 | Editorial Content | ... | ... | ... | A2
-I2 | Metadata and Data | ... | ... | ... | C3, C4
+I1 | Editorial Content | ... | ... | Indexing the posts and pages edited in Ghost | A2
+I2 | Metadata and Data | ... | ... | Indexing the metadata and data hosted, respectively, by data.grandlyon.com's catalog (C3) and database (C4) | C3, C4
## Services
@@ -121,12 +132,22 @@ In alphabetical order:
ID | Name | Repo | Doc | Usage | Deps
--- | --- | --- | --- | --- | ---
-S1 | Authentication | ... | ... | Allowing the users to create accounts and to perform logins and logouts | M1, S5
-S2 | Changelog | [Link](https://gitlab.alpha.grandlyon.com/refonte-data/service-changelog) | ... | Keeping track of the new features available to users througout the developments|
+S1 | Authentication | ... | ... | Allowing users to create accounts and to perform logins and logouts | M1, S5
+S2 | Changelog | [Link](https://gitlab.alpha.grandlyon.com/refonte-data/service-changelog) | ... | Keeping track of the new features available to users throughout the developments|
S3 | Credits | ... | ... | Catalog of the Open Source initiatives powering the data.grandlyon.com project | S6 |
S4 | CSV Catalog Downloader | ... | ... | Allowing users to download cached CSV exports of the metadata catalog | C3 |
-S5 | Mail | ... | [Link](../features/services/mail.md) | Sending e-mails to both end- and back-office users | A5
+S5 | Mail | ... | [Link](../features/services/mail.md) | Sending e-mails to both end- and back-office users | A6
S6 | Media Library | ... | ... | Managing the images shown across the various pages of the Web Portal (organizations, posts, ...) |
S7 | Organizations | ... | ... | A catalog of the partners of the data.grandlyon.com, typically Data Providers | S6
S8 | Resources Helper | ... | ... | Assisting users in the composition of custom queries against the Core APIs |
S9 | Reuses | ... | ... | A catalog of the known reuses of the data shared through data.grandlyon.com | S6
+
+## Specific applications
+ID | Name | Repo | Doc | Usage | Deps
+--- | --- | --- | --- | --- | ---
+D1 | Web App | ... | ... | Web Application representing the actual Web Portal as seen by its end-users | S[1,9]
+D2 | Admin GUI | ... | ... | Back-office oriented web application allowing users to administrate some of the editorial content as well as the configuration of some functionality | S[1,3], S[6,9]
+
+
+<!-- <span id="test">mon test</span>
+<a href='#test'>link</a> -->
diff --git a/mkdocs.yml b/mkdocs.yml
index 7e7bf965b7eab39830257ba99c3dde7a2d615ec7..6774d6bf85fbf90ba1db1d7875cfe46ddb31ea48 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,6 +1,6 @@
-site_name: Portail Data Functional Documentation
-site_description: Portail Data Project Documentation with Markdown.
-site_author: MkDocs Team
+site_name: Developer Guide
+#site_description: Portail Data Project Documentation with Markdown.
+site_author: Métropole de Lyon
theme:
name: null
@@ -22,24 +22,33 @@ markdown_extensions:
server: http://www.plantuml.com/plantuml
nav:
- - Home: index.md
- - Architecture Guide:
- - Admin-gui: architecture/admin-gui.md
- - Admin-tools: architecture/admin-tools.md
- - Api-gateway: architecture/api-gateway.md
- - CMS: architecture/cms.md
- - Monitoring: architecture/monitoring.md
- - Web-app: architecture/web-app.md
- - Authentication & Authorization: miscellaneous/authentication&authorization.md
- - Services:
- - authentication: architecture/services/authentication.md
- - organizations: architecture/services/organizations.md
- - resources: architecture/services/resources.md
- - Elasticsearch:
- - Indexer: architecture/services/elasticsearch/indexer.md
+ - Overview: overview/index.md
+ - Features: features/index.md
+ - Architecture: architecture/index.md
+ - Components:
+ - Core Components:
+ - Off-the-shelf applications:
+ - API Gateway: components/off-the-shelf-apps/api-gateway.md
+ - Headless CMS: components/off-the-shelf-apps/cms.md
+ - Search Engine: components/off-the-shelf-apps/elasticsearch.md
+ # - Middlewares:
+ # - Proxies:
+ - Indexers:
+ - Metadata and Data: components/indexers/metadata-and-data.md
+ - Editorial Content: components/indexers/editorial-content.md
+ - Services:
+ - Authentication: components/services/authentication.md
+ - Organizations: components/services/organizations.md
+ - Resources: components/services/resources.md
+ - Specific applications:
+ - Web App: components/specific-apps/web-app.md
+ - Admin GUI: components/specific-apps/admin-gui.md
+ - Administration: administration/admin-tools.md
+ - Monitoring: monitoring/monitoring.md
+ #- Authentication & Authorization: miscellaneous/authentication&authorization.md
- Other:
- - Gitflow: miscellaneous/gitflow-ci-cd.md
- - VSCode: miscellaneous/vscode-settings.md
- - SASS recommendation: miscellaneous/sass-recommendation.md
- - Webapp-auth: miscellaneous/webapp-auth.md
- - Multi-environment docker build for Angular app: miscellaneous/multi-environments-docker-build-for-angular
+ - Gitflow: miscellaneous/gitflow-ci-cd.md
+ - VSCode: miscellaneous/vscode-settings.md
+ - SASS recommendation: miscellaneous/sass-recommendation.md
+ - Webapp-auth: miscellaneous/webapp-auth.md
+ - Multi-environment docker build for Angular app: miscellaneous/multi-environments-docker-build-for-angular
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000000000000000000000000000000000000..ea6af1b2ddeb3f3c1350b8a7ec45be550268451b
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,3 @@
+mkdocs
+mkdocs-material
+plantuml-markdown