Add API references (frontend + backend) to documentation (#2765)

Add api references for both frontend and backend (also includes Utils-Flask-SQLAlchemy and Utils-Flask-SQLAlchemy-Geo). Change of the sphinx Github action. 
---------

Co-authored-by: TheoLechemia <[email protected]>

.github/workflows/cypress.yml

@@ -127,7 +127,6 @@ jobs:
           working-directory: ./frontend
           start: npm run start
           wait-on: http://127.0.0.1:4200
-          headless: true
         env:
           CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/sphinx.yml

@@ -1,6 +1,6 @@
 name: "Build Sphinx Documentation"
 
-on: 
+on:
   release:
     types: [published]
 
@@ -24,20 +24,37 @@ jobs:
           --health-timeout 5s
           --health-retries 5
     steps:
-    - uses: actions/setup-python@v4
-      with:
-        python-version: 3.9
-    - uses: actions/checkout@master
-      with:
-        fetch-depth: 0
-    - name: Build and Commit
-      uses: sphinx-notes/pages@v2
-      with:
-        requirements_path: docs/requirements.txt
-      env:
-        GEONATURE_CONFIG_FILE: config/test_config.toml
-    - name: Push changes
-      uses: ad-m/github-push-action@master
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        branch: gh-pages
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+      - uses: actions/checkout@master
+        with:
+          fetch-depth: 0
+          ref: update-doc
+
+      - name: Setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: lts/gallium
+
+      - name: Install JS librairies
+        working-directory: ./frontend
+        run: npm install
+
+      - name: Build JS documentation
+        working-directory: ./frontend
+        run: npm run docBuild
+
+      - name: Install python dependencies
+        run: pip install .[docs]
+
+      - name: Build and Commit
+        uses: sphinx-notes/pages@v2
+        env:
+          GEONATURE_CONFIG_FILE: config/test_config.toml
+
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages

.gitignore

@@ -97,6 +97,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/external_doc/documentation_js
 
 # PyBuilder
 target/

backend/requirements-dev.in

@@ -1,2 +1,2 @@
 -r requirements-common.in
--r requirements-submodules.in
+-r requirements-submodules.in

docs/api-references.rst

@@ -0,0 +1,9 @@
+API REFERENCES
+==============
+
+.. toctree::
+    ../../autoapi/geonature/index
+    ../../autoapi/pypnusershub/index
+    ../../autoapi/src/utils_flask_sqla/index
+    ../../autoapi/src/utils_flask_sqla_geo/index
+    frontend

docs/conf.py

@@ -17,6 +17,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import sys, os
+
+sys.path.insert(0, os.path.abspath("../backend"))
 
 # -- General configuration ------------------------------------------------
 
@@ -38,6 +41,13 @@
     "myst_parser",
 ]
 
+## AUTOAPI
+extensions.append("autoapi.extension")
+autoapi_dirs = ["../backend/geonature", "../backend/dependencies"]
+autoapi_ignore = ["*migrations*", "*tests*"]
+autoapi_add_toctree_entry = False
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -126,9 +136,7 @@
 #     ]
 # }
 
-html_extra_path = [
-    "CNAME",
-]
+html_extra_path = ["CNAME", "sources/"]
 
 
 # -- Options for HTMLHelp output ------------------------------------------
@@ -186,4 +194,4 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

docs/frontend.rst

@@ -0,0 +1,5 @@
+Frontend
+--------
+La documentation pour le frontend de Geonature se trouve ici_.
+
+.. _ici: documentation_js/index.html

docs/index.rst

@@ -11,3 +11,5 @@ Bienvenue dans la documentation de GeoNature
    FAQ
    authors
    CHANGELOG
+   api-references
+

docs/requirements.in

@@ -1,3 +1,4 @@
 sphinx
 sphinx_rtd_theme
 myst-parser
+sphinx-autoapi

docs/requirements.txt

@@ -1,18 +1,22 @@
 #
-# This file is autogenerated by pip-compile with python 3.7
-# To update, run:
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
 #
 #    pip-compile requirements.in
 #
-alabaster==0.7.12
+alabaster==0.7.13
     # via sphinx
-babel==2.10.3
+anyascii==0.3.2
+    # via sphinx-autoapi
+astroid==3.0.1
+    # via sphinx-autoapi
+babel==2.13.1
     # via sphinx
-certifi==2022.9.14
+certifi==2023.7.22
     # via requests
-charset-normalizer==2.1.1
+charset-normalizer==3.3.1
     # via requests
-docutils==0.17.1
+docutils==0.18.1
     # via
     #   myst-parser
     #   sphinx
@@ -21,63 +25,64 @@ idna==3.4
     # via requests
 imagesize==1.4.1
     # via sphinx
-importlib-metadata==4.12.0
-    # via sphinx
 jinja2==3.1.2
     # via
     #   myst-parser
     #   sphinx
-markdown-it-py==2.1.0
+    #   sphinx-autoapi
+markdown-it-py==3.0.0
     # via
     #   mdit-py-plugins
     #   myst-parser
-markupsafe==2.1.1
+markupsafe==2.1.3
     # via jinja2
-mdit-py-plugins==0.3.3
+mdit-py-plugins==0.4.0
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-myst-parser==0.18.1
+myst-parser==2.0.0
     # via -r requirements.in
-packaging==21.3
+packaging==23.2
     # via sphinx
-pygments==2.13.0
+pygments==2.16.1
     # via sphinx
-pyparsing==3.0.9
-    # via packaging
-pytz==2022.2.1
-    # via babel
-pyyaml==6.0
-    # via myst-parser
-requests==2.28.1
+pyyaml==6.0.1
+    # via
+    #   myst-parser
+    #   sphinx-autoapi
+requests==2.31.0
     # via sphinx
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==5.1.1
+sphinx==7.2.6
     # via
     #   -r requirements.in
     #   myst-parser
+    #   sphinx-autoapi
     #   sphinx-rtd-theme
-sphinx-rtd-theme==1.0.0
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-jquery
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
+sphinx-autoapi==3.0.0
     # via -r requirements.in
-sphinxcontrib-applehelp==1.0.2
+sphinx-rtd-theme==1.3.0
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.7
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==1.0.5
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-htmlhelp==2.0.4
     # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==1.0.6
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.9
     # via sphinx
-typing-extensions==4.3.0
-    # via
-    #   importlib-metadata
-    #   markdown-it-py
-    #   myst-parser
-urllib3==1.26.12
+urllib3==2.0.7
     # via requests
-zipp==3.8.1
-    # via importlib-metadata