Merge pull request #10684 from camptocamp/backport/10681-to-2.7

[Backport 2.7] Fix doccumentation issues

Makefile

@@ -1,6 +1,7 @@
 MAJOR_VERSION ?= $(shell scripts/get-version --major)
 MAJOR_MINOR_VERSION ?= $(shell scripts/get-version --major-minor)
 VERSION ?= $(shell scripts/get-version --full)
+MAIN_BRANCH ?= fake-local-branch
 DOCKER_TAG ?= latest
 export DOCKER_BUILDKIT=1
 
@@ -121,4 +122,4 @@ doc: build-tools ## Generate the documentation
 	--build-arg=MAJOR_VERSION=$(MAJOR_VERSION) \
 	--build-arg=MAIN_BRANCH=$(MAIN_BRANCH) \
 	doc
-	MAJOR_VERSION=$(MAJOR_VERSION) MAIN_BRANCH=$(MAIN_BRANCH) ci/extract-documentation artifacts/documentations/
+	ci/extract-documentation artifacts/documentations/

ci/extract-documentation

@@ -1,10 +1,6 @@
 #!/bin/bash -eux
 
-mkdir --parent ${1}
-docker build --tag=camptocamp/geomapfish-doc \
-    --build-arg=MAJOR_VERSION=${MAJOR_VERSION} \
-    --build-arg=MAIN_BRANCH=${MAIN_BRANCH} \
-    doc
+mkdir --parent "${1}"
 docker run --rm --name=doc --detach camptocamp/geomapfish-doc tail -f /dev/null
 docker cp doc:/doc/_build/html/ ${1}/
 docker stop doc

doc/Dockerfile

@@ -33,9 +33,10 @@ WORKDIR /doc
 ARG MAJOR_VERSION
 ARG MAIN_BRANCH
 
-RUN ./import_ngeo_config.py --type Configuration integrator/ngeo_configuration.rst \
-      --type APIConfig integrator/ngeo_api_configuration.rst \
-      node_modules/ngeo/dist/typedoc.json integrator/ngeo_other_configuration.rst && \
+RUN ./import_ngeo_config.py \
+      --type Configuration /ngeo_configuration.rst \
+      --type APIConfig /ngeo_api_configuration.rst \
+      node_modules/ngeo/dist/typedoc.json /ngeo_other_configuration.rst && \
+    mv integrator/ngeo_config_ref.rst / && \
     mkdir --parent _build/html && \
-    sphinx-build -b html -d _build/doctrees . _build/html && \
-    ./build.sh
+    sphinx-build -W -b html -d _build/doctrees . _build/html

doc/Pipfile

@@ -14,7 +14,7 @@ Sphinx-Substitution-Extensions = { extras = [
     "prompt"
 ], version = "==2022.2.16" }
 sphinxcontrib-mermaid = "==0.7.1"
-#tilecloud-chain = "==1.17.0.dev20220131092647"
+tilecloud-chain = "==1.17.4"
 # Lock dependencies
 babel = "==2.9.1"
 certifi = "==2023.7.22"
@@ -32,12 +32,7 @@ pytz = "==2021.3"
 pyyaml = "==6.0.1"
 requests = "==2.31.0"
 snowballstemmer = "==2.2.0"
-sphinxcontrib-applehelp = "==1.0.7"
-sphinxcontrib-devhelp = "==1.0.5"
-sphinxcontrib-htmlhelp = "==2.0.4"
 sphinxcontrib-jsmath = "==1.0.1"
-sphinxcontrib-qthelp = "==1.0.6"
-sphinxcontrib-serializinghtml = "==1.1.9"
 urllib3 = "==1.26.16"
 venusian = "==3.0.0"
 webob = "==1.8.7"

doc/conf.py

@@ -125,7 +125,11 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {"github_user": "camptocamp", "github_repo": "c2cgeoportal", "github_banner": True}
+html_theme_options = {
+    "github_user": "camptocamp",
+    "github_repo": "c2cgeoportal",
+    "github_banner": False,
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

doc/import_ngeo_config.py

@@ -86,7 +86,11 @@ def main() -> None:
     """Convert the ngeo config to ReStructuredText."""
     parser = argparse.ArgumentParser("Convert the config from the JSON from typedoc to ReStructuredText")
     parser.add_argument(
-        "--type", help="create a separate file for a type", nargs=2, action="append", default=[]
+        "--type",
+        help="create a separate file for a type",
+        nargs=2,
+        action="append",
+        default=[],
     )
     parser.add_argument("input", help="the JSON file from typedoc")
     parser.add_argument("other", help="filename for other types")

doc/integrator/authentication.rst

@@ -20,16 +20,14 @@ application's main ``__init__.py`` file.
 
 In the file ``env.project``, you can configure the policy with the following variables:
 
-.. code::
-
-   AUTHTKT_TIMEOUT  # Default to one day.
-   AUTHTKT_REISSUE_TIME  # Default to 2h30, recommended to be 10 times smaller than AUTHTKT_TIMEOUT.
-   AUTHTKT_MAXAGE  # Default to one day, good to have the same value as AUTHTKT_TIMEOUT.
-   AUTHTKT_SECRET  # Should be defined
-   AUTHTKT_COOKIENAME
-   AUTHTKT_HTTP_ONLY  # Default to true.
-   AUTHTKT_SECURE  # Default to true.
-   AUTHTKT_SAMESITE  # Default to Lax.
+``AUTHTKT_TIMEOUT``: Default to one day.
+``AUTHTKT_REISSUE_TIME``: Default to 2h30, recommended to be 10 times smaller than ``AUTHTKT_TIMEOUT``.
+``AUTHTKT_MAXAGE``: Default to one day, good to have the same value as ``AUTHTKT_TIMEOUT``.
+``AUTHTKT_SECRET``: Should be defined
+``AUTHTKT_COOKIENAME``: Should be defined
+``AUTHTKT_HTTP_ONLY``: Default to ``true``.
+``AUTHTKT_SECURE``: Default to ``true``.
+``AUTHTKT_SAMESITE``: Default to ``Lax``.
 
 .. note::
 

doc/integrator/create_application.rst

@@ -340,25 +340,27 @@ it can be obtained with:
 
 In the `Makefile` you should add something like:
 
-```
-DUMP_FILE=dump.backup
-
-.PHONY: acceptance-init
-acceptance-init: ## Initialize the acceptance tests
-    docker-compose --file=docker-compose.yaml --file=docker-compose-db.yaml up -d
-    docker-compose exec -T geoportal wait-db
-    docker-compose exec -T tools psql --command="DROP EXTENSION IF EXISTS postgis CASCADE"
-    scripts/db-restore --docker-compose-file=docker-compose.yaml --docker-compose-file=docker-compose-db.yaml \
-        --arg=--clean --arg=--if-exists --arg=--verbose $(DUMP_FILE)
-
-.PHONY: acceptance
-acceptance: ## Run the acceptance tests
-    docker-compose exec -T tools pytest -vv tests/
-```
+.. code:: make
+
+    DUMP_FILE=dump.backup
+
+    .PHONY: acceptance-init
+    acceptance-init: ## Initialize the acceptance tests
+        docker-compose --file=docker-compose.yaml --file=docker-compose-db.yaml up -d
+        docker-compose exec -T geoportal wait-db
+        docker-compose exec -T tools psql --command="DROP EXTENSION IF EXISTS postgis CASCADE"
+        scripts/db-restore --docker-compose-file=docker-compose.yaml --docker-compose-file=docker-compose-db.yaml \
+            --arg=--clean --arg=--if-exists --arg=--verbose $(DUMP_FILE)
+
+    .PHONY: acceptance
+    acceptance: ## Run the acceptance tests
+        docker-compose exec -T tools pytest -vv tests/
+
 
 In the file `.github/workflows/main.yaml` you should add something like:
 
-```yaml
+.. code:: yaml
+
       - name: Initialize the acceptance tests
         run: make acceptance-init
       - run: c2cciutils-docker-logs
@@ -369,83 +371,82 @@ In the file `.github/workflows/main.yaml` you should add something like:
       - run: c2cciutils-docker-logs
         if: always()
 
-```
-
 You should add a `docker-compose-db.yaml` file, with:
 
-```
-# This file is used by the acceptance tests to have a local database.
-
-version: '2.3'
-
-volumes:
-  postgresql_data:
-
-services:
-  config: &db-config
-    environment:
-      - PGHOST=db
-      - PGHOST_SLAVE=db
-      - PGSSLMODE=prefer
-  geoportal: *db-config
-  # geoportal-advance: *db-config
-  tools: *db-config
-  alembic: *db-config
-  # alembic-advance: *db-config
-  # webpack_dev_server: *db-config
-
-  db:
-    extends:
-      file: docker-compose-lib.yaml
-      service: db
+.. code:: yaml
+
+    # This file is used by the acceptance tests to have a local database.
+
+    version: '2.3'
+
     volumes:
-      - postgresql_data:/var/lib/postgresql/data
-```
+    postgresql_data:
+
+    services:
+    config: &db-config
+        environment:
+        - PGHOST=db
+        - PGHOST_SLAVE=db
+        - PGSSLMODE=prefer
+    geoportal: *db-config
+    # geoportal-advance: *db-config
+    tools: *db-config
+    alembic: *db-config
+    # alembic-advance: *db-config
+    # webpack_dev_server: *db-config
+
+    db:
+        extends:
+        file: docker-compose-lib.yaml
+        service: db
+        volumes:
+        - postgresql_data:/var/lib/postgresql/data
+
 
 And finally the file with the tests `tests/test_app.py` with:
 
-```
-import time
-from typing import Dict
-
-import pytest
-import requests
-
-
-@pytest.mark.parametrize(
-    "url,params",
-    [
-        ("https://front", {}),
-        ("https://front/themes", {}),
-        ("https://front/static-geomapfish/0/locales/fr.json", {}),
-        ("https://front/dynamic.json", {"interface": "desktop"}),
-        ("https://front/dynamic.json", {"interface": "desktop", "query": "", "path": "/"}),
-        ("https://front/c2c/health_check", {}),
-        ("https://front/c2c/health_check", {"max_level": "1"}),
-        ("https://front/c2c/health_check", {"checker": "check_collector"}),
-        ("https://front/admin/layertree", {}),
-        ("https://front/admin/layertree/children", {}),
-        ("http://mapserver:8080/mapserv_proxy", {"SERVICE": "WMS", "REQUEST": "GetCapabilities"}),
-        (
-            "https://front/mapserv_proxy",
-            {"ogcserver": "source for image/png", "SERVICE": "WMS", "REQUEST": "GetCapabilities"},
-        ),
-    ],
-)
-def test_url(url: str, params: Dict[str, str]) -> None:
-    """Tests that some URL didn't return an error."""
-    for _ in range(60):
-        response = requests.get(url, params=params, verify=False, timeout=240)  # nosec
-        if response.status_code == 503:
-            time.sleep(1)
-            continue
-        break
-    assert response.status_code == 200, response.text
-
-
-def test_admin() -> None:
-    """Tests that the admin page will provide the login page."""
-    response = requests.get("https://front/admin/", verify=False, timeout=240)  # nosec
-    assert response.status_code == 200, response.text
-    assert "Login" in response.text
-```
+.. code:: python
+
+    import time
+    from typing import Dict
+
+    import pytest
+    import requests
+
+
+    @pytest.mark.parametrize(
+        "url,params",
+        [
+            ("https://front", {}),
+            ("https://front/themes", {}),
+            ("https://front/static-geomapfish/0/locales/fr.json", {}),
+            ("https://front/dynamic.json", {"interface": "desktop"}),
+            ("https://front/dynamic.json", {"interface": "desktop", "query": "", "path": "/"}),
+            ("https://front/c2c/health_check", {}),
+            ("https://front/c2c/health_check", {"max_level": "1"}),
+            ("https://front/c2c/health_check", {"checker": "check_collector"}),
+            ("https://front/admin/layertree", {}),
+            ("https://front/admin/layertree/children", {}),
+            ("http://mapserver:8080/mapserv_proxy", {"SERVICE": "WMS", "REQUEST": "GetCapabilities"}),
+            (
+                "https://front/mapserv_proxy",
+                {"ogcserver": "source for image/png", "SERVICE": "WMS", "REQUEST": "GetCapabilities"},
+            ),
+        ],
+    )
+    def test_url(url: str, params: Dict[str, str]) -> None:
+        """Tests that some URL didn't return an error."""
+        for _ in range(60):
+            response = requests.get(url, params=params, verify=False, timeout=240)  # nosec
+            if response.status_code == 503:
+                time.sleep(1)
+                continue
+            break
+        assert response.status_code == 200, response.text
+
+
+    def test_admin() -> None:
+        """Tests that the admin page will provide the login page."""
+        response = requests.get("https://front/admin/", verify=False, timeout=240)  # nosec
+        assert response.status_code == 200, response.text
+        assert "Login" in response.text

doc/integrator/docker.rst

@@ -56,6 +56,7 @@ For OpenShift projects:
         tinyows -.-> postgres;
 
         classDef data fill:#5ba6ff,color:black;
+
 For standalone projects:
 
 .. mermaid::

doc/integrator/extend_application.rst

@@ -361,7 +361,7 @@ For that you will need to create a new folder named ``geoportal_custom``.
 
 An this folder, add a file named ``authentication.py`` with the content you need, the original content is:
 
-.. code:: python:
+.. code:: python
 
    from pyramid.config import Configurator
 

doc/integrator/headers.rst

@@ -18,7 +18,7 @@ You may wish to override the values being written. All this is done in the confi
           cache_control_max_age: 600 # 10 minutes
           access_control_max_age: 600 # 10 minutes
           access_control_allow_origin: [] # list oh hosts (e.g. https://example.com) or '*'
-          headers: {} @ list of additional headers
+          headers: {} # list of additional headers
 
 Where ``<view>`` can be: ``dynamic``, ``index``, ``api``, ``apihelp``, ``profile``, ``raster``, ``error``,
 ``themes``, ``config``, ``print``, ``fulltextsearch``, ``mapserver``, ``tinyows``, ``layers``,

doc/integrator/https.rst

@@ -1,3 +1,4 @@
+-----
 HTTPS
 -----
 
@@ -12,7 +13,7 @@ There are two ways to manage this:
 * application and SSL certificate on the same server
 
 Application behind a proxy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 If the application is placed behind some proxy that removes the SSL encryption
 (plain HTTP is used between the proxy and the server), then some specific
@@ -35,7 +36,7 @@ value of ``request.scheme``. For example::
     };
 
 Application and SSL certificate on the same server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------
 
 If the SSL certificate and the application are located on the same server, all
 requests will be redirected to https. So you should change the scheme to https
@@ -52,7 +53,7 @@ In case you load http external resources into your application, you should use
 the resourceproxy service as described below.
 
 Loading non https external resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
 
 If you want to load non https external resources in your https application, you
 should use the ``resourceproxy`` service and add the list of hosts you want to access in your project
@@ -74,7 +75,7 @@ For example:
 ``https://geoportail.camptocamp.com/main/resourceproxy?target=rfinfo&values=(175,2633)``
 
 Local certificate checks
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 Certain c2cgeoportal features open a http session to your c2cgeoportal services,
 for example the ``checker`` or the ``lingua_extractor``.