feat: documentation generation

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: documentation/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: web/requirements.doc.txt

Makefile

@@ -4,7 +4,7 @@
 
 install-dev:
 	# Install dependencies for local development usage
-	poetry env use 3.8 ; poetry install --with dev ; poetry shell
+	poetry env use 3.8 ; poetry install --with dev --with doc ; poetry shell
 	pre-commit install
 
 export-base-dependencies:
@@ -15,6 +15,10 @@ export-dev-dependencies:
 	# Update requirements file for development environment used in GitHub Actions
 	poetry export --without-hashes --only dev -o web/requirements.dev.txt
 
+export-doc-dependencies:
+	# Update requirements file for development environment used in GitHub Actions
+	poetry export --without-hashes --only doc -o web/requirements.doc.txt
+
 translation-extract:
 	# Extract messages to be translated with:
 	pybabel extract --mapping-file web/translations/babel.cfg --output-file web/translations/messages.pot --keywords lazy_gettext web
@@ -26,3 +30,6 @@ translation-update:
 translation-compile:
 	# Compile translation catalogs with:
 	pybabel compile --directory web/translations
+
+doc:
+	sphinx-build documentation build/sphinx/html

documentation/conf.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+import datetime
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../web"))
+sys.path.insert(0, os.path.abspath("../web/flaskr"))
+
+
+# -- General configuration ------------------------------------------------
+
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.autodoc_pydantic",
+]
+
+templates_path = ["_templates"]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+master_doc = "index"
+project = "flaskr"
+year = datetime.datetime.now().strftime("%Y")
+copyright = f"{year}, Ministère de l'Éducation Nationale"
+author = "Ministère de l'Éducation Nationale"
+
+release = "1.1.0"  # metadata.version("flaskr")
+version = "%s.%s" % tuple(map(int, release.split(".")[:2]))
+language = "fr"
+exclude_patterns = []
+pygments_style = "sphinx"
+todo_include_todos = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# -- Options for HTML output ----------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = []
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+htmlhelp_basename = "b3deskdoc"
+html_logo = ""
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {}
+latex_documents = [
+    (
+        master_doc,
+        "b3desk.tex",
+        "B3Desk Documentation",
+        "Ministère de l’Éducation Nationale",
+        "manual",
+    )
+]
+
+# -- Options for manual page output ---------------------------------------
+
+man_pages = [(master_doc, "b3desk", "B3Desk Documentation", [author], 1)]
+
+# -- Options for Texinfo output -------------------------------------------
+
+texinfo_documents = [
+    (
+        master_doc,
+        "b3desk",
+        "B3Desk Documentation",
+        author,
+        "B3Desk",
+        "BBB frontend by the French Ministry of Education.",
+        "Miscellaneous",
+    )
+]
+
+# -- Options for autodo_pydantic_settings -------------------------------------------
+
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_show_validator_summary = False
+autodoc_pydantic_model_show_validator_members = False
+autodoc_pydantic_model_show_field_summary = False
+autodoc_pydantic_field_list_validators = False

documentation/index.rst

@@ -0,0 +1,23 @@
+B3Desk
+======
+
+Frontend Big Blue Button du Ministère de l’Éducation Nationale.
+
+Table des matières
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   settings
+   dockerPersistence
+   meetingFiles
+   pullRequestValidation
+   translation
+
+Index et tables
+===============
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

documentation/settings.rst

@@ -0,0 +1,4 @@
+Configuration
+#############
+
+.. autopydantic_model:: flaskr.settings.MainSettings