Feature: docs example notebooks (#534)

* Add example notebooks as jupytext python scripts
* Update example model graphics
* Add jupyter kernel install to RTD config
* Add CBC to RTD build

---------

Co-authored-by: Stefan Pfenninger <stefan@pfenninger.org>

.pre-commit-config.yaml

@@ -13,13 +13,6 @@ repos:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
 
-  - repo: https://github.com/nbQA-dev/nbQA
-    rev: 1.7.1
-    hooks:
-      - id: nbqa-black
-      - id: nbqa-ruff
-        args: [--fix, --exit-non-zero-on-fix]
-
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:

.readthedocs.yml

@@ -7,9 +7,9 @@ build:
     python: mambaforge-4.10
   jobs:
     post_create_environment:
-      - mamba install python=3.11 --file requirements/docs.txt
+      - mamba install python=3.12 coin-or-cbc --file requirements/docs.txt
       - pip install --no-deps .
-
+      - python -m ipykernel install --user --name calliope_docs_build
 
 mkdocs:
   configuration: mkdocs.yml

CHANGELOG.md

@@ -35,12 +35,13 @@ Then, all transmission links will be given their name as defined in `techs` rath
 |changed| |backwards-incompatible| Flow efficiencies are now split into inflow (`flow_in_eff`) and outflow (`flow_out_eff`) efficiencies. This enables different storage charge/discharge efficiencies to be applied.
 
 |changed| |backwards-incompatible| Mass parameter and decision variable renaming for increased clarity:
-    * `energy`/`carrier` → `flow`, e.g. `energy_cap` is now `flow_cap`.
-    * `prod`/`con` → `out`/`in`, e.g., `carrier_prod` is now `flow_out`.
-    * `resource` has been split into `source` (for things entering the model) and `sink` (for things leaving the model).
-    * `resource_area` is now `area_use`.
-    * `energy_cap_min_use` is now `flow_out_min_relative` (i.e., the value is relative to `flow_cap`).
-    * `parasitic_eff` is now `flow_out_parasitic_eff`.
+
+* `energy`/`carrier` → `flow`, e.g. `energy_cap` is now `flow_cap`.
+* `prod`/`con` → `out`/`in`, e.g., `carrier_prod` is now `flow_out`.
+* `resource` has been split into `source` (for things entering the model) and `sink` (for things leaving the model).
+* `resource_area` is now `area_use`.
+* `energy_cap_min_use` is now `flow_out_min_relative` (i.e., the value is relative to `flow_cap`).
+* `parasitic_eff` is now `flow_out_parasitic_eff`.
 
 |changed| |backwards-incompatible| Time masking and clustering capabilities have been severely reduced. Time resampling and clustering are now accessible by top-level configuration keys: e.g., `config.init.time_resample: 2H`, `config.init.time_cluster: cluster_file.csv`. Clustering is simplified to only matching model dates to representative days, with those representative days being in the clustered timeseries. Masking/clustering data should now be undertaken by the user prior to initialising a Calliope model.