Upddate documentation

Author: lucas-vivier

.github/workflows/docs.yml

@@ -27,21 +27,43 @@ jobs:
           python-version: '3.8'
 
       - name: Install dependencies
-        run: pip install -r docs/requirements.txt
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
 
-      - name: Build Sphinx docs
+      - name: Build Sphinx HTML (warnings are errors)
         run: |
           cd docs
-          make clean
-          make html
+          sphinx-build -b html -W --keep-going source _build/html
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs/_build/html/
 
+  linkcheck:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.8'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Run linkcheck (warnings are errors)
+        run: |
+          cd docs
+          sphinx-build -b linkcheck -W --keep-going source _build/linkcheck
+
   deploy:
-    if: github.ref == 'refs/heads/master'
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
     needs: build
     runs-on: ubuntu-latest
     environment:

docs/requirements.txt

@@ -1,6 +1,6 @@
-sphinx>=5.0
-pydata-sphinx-theme>=0.14
-myst-parser>=0.18
-nbsphinx>=0.9
-sphinxcontrib-bibtex>=2.5
-sphinx-copybutton
+sphinx>=7.0,<8.0
+pydata-sphinx-theme>=0.14,<0.16
+myst-parser>=2.0,<3.0
+nbsphinx>=0.9,<0.10
+sphinxcontrib-bibtex>=2.6,<3.0
+sphinx-copybutton>=0.5,<0.6

docs/source/_static/custom.css

@@ -16,3 +16,37 @@
 .bd-sidebar-primary {
   border-right: 1px solid var(--pst-color-border);
 }
+
+/* Keep the primary sidebar visible and sticky on desktop */
+@media (min-width: 992px) {
+  .bd-sidebar-primary {
+    display: block !important;
+    visibility: visible !important;
+    transform: none !important;
+    margin-left: 0 !important;
+    position: sticky;
+    top: calc(var(--pst-header-height) + 0.5rem);
+    max-height: calc(100vh - var(--pst-header-height) - 1rem);
+    overflow-y: auto;
+  }
+
+  body:not(.primary-sidebar-open) .bd-sidebar-primary {
+    margin-left: 0 !important;
+  }
+}
+
+/* Improve long-form readability */
+.bd-content .bd-article {
+  line-height: 1.65;
+}
+
+.bd-content .bd-article h1,
+.bd-content .bd-article h2,
+.bd-content .bd-article h3 {
+  letter-spacing: 0.01em;
+}
+
+/* Make admonitions slightly easier to scan */
+.bd-content .admonition {
+  border-radius: 0.4rem;
+}

docs/source/api/building.rst

@@ -3,6 +3,17 @@ Building
 
 Core agent-based model: household behavior, renovation decisions, and heating system choices.
 
+When to use this module
+-----------------------
+
+Use ``project.building`` when you need to inspect or extend behavior at dwelling and agent level, including:
+
+- renovation choice logic
+- heating-system switching behavior
+- stock state transitions on the agent side
+
+Main classes are exposed through ``ThermalBuildings`` and ``AgentBuildings``.
+
 .. automodule:: project.building
    :members:
    :undoc-members:

docs/source/api/coupling.rst

@@ -3,6 +3,11 @@ Coupling
 
 Scenario coupling logic for integrated policy analysis.
 
+When to use this module
+-----------------------
+
+Use ``project.coupling`` for multi-run workflows where Res-IRF outputs are reused as inputs for iterative or linked analyses.
+
 .. automodule:: project.coupling
    :members:
    :undoc-members:

docs/source/api/dynamic.rst

@@ -3,6 +3,15 @@ Dynamic
 
 Exogenous dynamics: stock needs, construction flows, and housing type transitions.
 
+When to use this module
+-----------------------
+
+Use ``project.dynamic`` when working with:
+
+- population-to-stock transformations
+- construction need projections
+- housing-type and surface evolution rules
+
 .. automodule:: project.dynamic
    :members:
    :undoc-members:

docs/source/api/model.rst

@@ -3,6 +3,17 @@ Model
 
 Main simulation engine: initialization, calibration, and scenario execution.
 
+When to use this module
+-----------------------
+
+Use ``project.model`` when you need to:
+
+- prepare scenario configurations before execution
+- initialize model state from parsed inputs
+- run a full simulation programmatically
+
+Common entrypoints include ``prepare_config`` and ``res_irf``.
+
 .. automodule:: project.model
    :members:
    :undoc-members:

docs/source/api/read_input.rst

@@ -3,6 +3,17 @@ Read Input
 
 Data loading and policy parsing: reads configuration files, building stock data, and policy definitions.
 
+When to use this module
+-----------------------
+
+Use ``project.read_input`` for:
+
+- reading stock, macro, and technical inputs
+- parsing policy definitions into internal objects
+- transforming raw tables into model-ready structures
+
+This module also defines policy object abstractions used across the run pipeline.
+
 .. automodule:: project.read_input
    :members:
    :undoc-members:

docs/source/api/runs.rst

@@ -3,6 +3,11 @@ Runs
 
 Scenario execution utilities.
 
+When to use this module
+-----------------------
+
+Use ``project.runs`` to execute a directory of configuration files in batch mode from the CLI.
+
 .. automodule:: project.runs
    :members:
    :undoc-members:

docs/source/api/thermal.rst

@@ -3,6 +3,15 @@ Thermal
 
 Thermal building calculations: energy performance, heat loss, and EPC classification.
 
+When to use this module
+-----------------------
+
+Use ``project.thermal`` for:
+
+- conventional and actual energy-use calculations
+- EPC/certificate assignment helpers
+- heating-intensity and thermal-physics utility functions
+
 .. automodule:: project.thermal
    :members:
    :undoc-members: