Updates in response to review

* Removed `ruamel.yaml`, `myst-parser` and `nbconvert` from requirements
calliope-project · Dec 21, 2023 · fe2c05f · fe2c05f
1 parent e3617ce
commit fe2c05f
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 35 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -2,13 +2,18 @@
 
 !!! note
 
-    This is the documentation for version {{ version }} ([Version history](version_history.md)). See the [main project website at www.callio.pe](https://www.callio.pe/) for more general information, including a gallery of models built with Calliope, and other useful information.
+    This is the documentation for version {{ version }} ([Version history](version_history.md)).
+    See the [main project website at www.callio.pe](https://www.callio.pe/) for more general information, including a gallery of models built with Calliope, and other useful information.
 
-Calliope focuses on flexibility, high spatial and temporal resolution, the ability to execute many runs based on the same base model, and a clear separation of framework (code) and model (data). Its primary focus is on planning energy systems at scales ranging from urban districts to entire continents. In an optional operational mode it can also test a pre-defined system under different operational conditions. Calliope's built-in tools allow interactive exploration of results.
+Calliope focuses on flexibility, high spatial and temporal resolution, the ability to execute many runs based on the same base model, and a clear separation of framework (code) and model (data).
+Its primary focus is on planning energy systems at scales ranging from urban districts to entire continents.
+In an optional operational mode it can also test a pre-defined system under different operational conditions.
+Calliope's built-in tools allow interactive exploration of results.
 
 [TODO: PLOT HERE]
 
-A model based on Calliope consists of a collection of text files (in YAML and CSV formats) that define the technologies, locations and resource potentials. Calliope takes these files, constructs an optimisation problem, solves it, and reports results in the form of [xarray Datasets](https://docs.xarray.dev/en/v2022.03.0/user-guide/data-structures.html#dataset) which in turn can easily be converted into [Pandas data structures](https://pandas.pydata.org/pandas-docs/version/1.5/user_guide/dsintro.html#dsintro) for easy analysis with Calliope's built-in tools or the standard Python data analysis stack.
+A model based on Calliope consists of a collection of text files (in YAML and CSV formats) that define the technologies, locations and resource potentials.
+Calliope takes these files, constructs an optimisation problem, solves it, and reports results in the form of [xarray Datasets](https://docs.xarray.dev/en/v2022.03.0/user-guide/data-structures.html#dataset) which in turn can easily be converted into [Pandas data structures](https://pandas.pydata.org/pandas-docs/version/1.5/user_guide/dsintro.html#dsintro) for easy analysis with Calliope's built-in tools or the standard Python data analysis stack.
 
 Calliope is developed in the open [on GitHub](https://github.com/calliope-project/calliope) and contributions are very welcome (see TODO: LINK:`user/develop`).
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -31,7 +31,10 @@ To use Calliope, you need to activate the `calliope` environment each time
 $ mamba activate calliope
 ```
 
-You are now ready to use Calliope together with the free and open source GLPK solver. However, we recommend to not use this solver where possible, since it performs relatively poorly (both in solution time and stability of result). Indeed, our example models use the free and open source CBC solver instead, but installing it on Windows requires an extra step. Read the next section for more information on installing alternative solvers.
+You are now ready to use Calliope together with the free and open source GLPK solver.
+However, we recommend to not use this solver where possible, since it performs relatively poorly (both in solution time and stability of result).
+Indeed, our example models use the free and open source CBC solver instead, but installing it on Windows requires an extra step.
+Read the next section for more information on installing alternative solvers.
 
 !!! warning
 
@@ -52,23 +55,30 @@ You need at least one of the solvers supported by Pyomo installed. CBC (open-sou
 
 ### CBC
 
-[CBC](https://github.com/coin-or/Cbc) is our recommended option if you want a free and open-source solver. CBC can be installed via conda on Linux and macOS by running `mamba install -c conda-forge coincbc`. Windows binary packages are somewhat more difficult to install, due to limited information on [the CBC website](https://github.com/coin-or/Cbc), but can be found within their [binary archive](https://www.coin-or.org/download/binary/Cbc/) and are included in their [package releases on GitHub](https://github.com/coin-or/Cbc/releases). The GitHub releases are more up-to-date. We recommend you download the relevant binary for [CBC 2.10.8](https://github.com/coin-or/Cbc/releases/download/releases%2F2.10.8/Cbc-releases.2.10.8-w64-msvc17-md.zip) and add `cbc.exe` to a directory known to PATH (e.g. an Anaconda environment 'bin' directory).
+[CBC](https://github.com/coin-or/Cbc) is our recommended option if you want a free and open-source solver.
+CBC can be installed via conda on Linux and macOS by running `mamba install -c conda-forge coincbc`.
+Windows binary packages are somewhat more difficult to install, due to limited information on [the CBC website](https://github.com/coin-or/Cbc), but can be found within their [binary archive](https://www.coin-or.org/download/binary/Cbc/) and are included in their [package releases on GitHub](https://github.com/coin-or/Cbc/releases).
+The GitHub releases are more up-to-date. We recommend you download the relevant binary for [CBC 2.10.8](https://github.com/coin-or/Cbc/releases/download/releases%2F2.10.8/Cbc-releases.2.10.8-w64-msvc17-md.zip) and add `cbc.exe` to a directory known to PATH (e.g. an Anaconda environment 'bin' directory).
 
 ### GLPK
 
-[GLPK](https://www.gnu.org/software/glpk/) is free and open-source, but can take too much time and/or too much memory on larger problems. If using the recommended installation approach above, GLPK is already installed in the `calliope` environment. To install GLPK manually, refer to the [GLPK website](https://www.gnu.org/software/glpk/).
+[GLPK](https://www.gnu.org/software/glpk/) is free and open-source, but can take too much time and/or too much memory on larger problems.
+If using the recommended installation approach above, GLPK is already installed in the `calliope` environment.
+To install GLPK manually, refer to the [GLPK website](https://www.gnu.org/software/glpk/).
 
 ### Gurobi
 
-[Gurobi](https://www.gurobi.com/) is commercial but significantly faster than CBC and GLPK, which is relevant for larger problems. It needs a license to work, which can be obtained for free for academic use by creating an account on gurobi.com.
+[Gurobi](https://www.gurobi.com/) is commercial but significantly faster than CBC and GLPK, which is relevant for larger problems.
+It needs a license to work, which can be obtained for free for academic use by creating an account on gurobi.com.
 
 While Gurobi can be installed via conda (`mamba install -c gurobi gurobi`) we recommend downloading and installing the installer from the [Gurobi website](https://www.gurobi.com/), as the conda package has repeatedly shown various issues.
 
 After installing, log on to the [Gurobi website](https://www.gurobi.com/) and obtain a (free academic or paid commercial) license, then activate it on your system via the instructions given online (using the `grbgetkey` command).
 
 ### CPLEX
 
-Another commercial alternative is [CPLEX](https://www.ibm.com/products/ilog-cplex-optimization-studio). IBM offer academic licenses for CPLEX. Refer to the IBM website for details.
+Another commercial alternative is [CPLEX](https://www.ibm.com/products/ilog-cplex-optimization-studio).
+IBM offer academic licenses for CPLEX. Refer to the IBM website for details.
 
 ## Python module requirements
 

diff --git a/docs/pre_build/generate_math.py b/docs/pre_build/generate_math.py
@@ -14,7 +14,7 @@
 import pandas as pd
 
 BASEPATH = Path(__file__).resolve().parent
-STATICPATH = BASEPATH / ".." / "_static"
+
 NONDEMAND_TECHGROUPS = [
     "supply",
     "storage",
@@ -26,7 +26,7 @@
 
 
 def generate_base_math_model(model_config: dict) -> calliope.Model:
-    """Generate RST file for the base math
+    """Generate model with documentation for the base math
 
     Args:
         model_config (dict): Calliope model config.
@@ -38,24 +38,21 @@ def generate_base_math_model(model_config: dict) -> calliope.Model:
         model_definition=model_config, timeseries_dataframes=_ts_dfs()
     )
     model.math_documentation.build()
-    model.math_documentation.write(STATICPATH / "math.rst")
     return model
 
 
 def generate_custom_math_model(
     base_model: calliope.Model,
     model_config: dict,
     model_config_updates: dict,
-    name: str,
-) -> None:
-    """Generate RST file for a built-in custom math file, showing only the changes made
+) -> calliope.Model:
+    """Generate model with documentation for a built-in custom math file, showing only the changes made
     relative to the base math.
 
     Args:
         base_model (calliope.Model): Calliope model with only the base math applied.
         model_config (dict): Model config suitable for generating the base math.
         model_config_updates (dict): Changes to make to the model config to load the custom math.
-        name (str): Name of the custom math to add to the file name.
     """
     model_config = calliope.AttrDict(model_config)
     model_config_updates = calliope.AttrDict(model_config_updates)
@@ -67,7 +64,7 @@ def generate_custom_math_model(
     )
     _keep_only_changes(base_model, model)
 
-    model.math_documentation.write(STATICPATH / f"math_{name}.rst")
+    return model
 
 
 def generate_model_config() -> dict[str, dict]:
@@ -162,14 +159,14 @@ def _keep_only_changes(base_model: calliope.Model, model: calliope.Model) -> Non
             if name in base_model.math[component_group]:
                 if not component_dict.get("active", True):
                     expr_del.append(name)
-                    component_dict["description"] = ":red:`REMOVED`"
+                    component_dict["description"] = "|REMOVED|"
                     component_dict["active"] = True
                 elif base_model.math[component_group].get(name, {}) != component_dict:
-                    _add_to_description(component_dict, ":yellow:`UPDATED`")
+                    _add_to_description(component_dict, "|UPDATED|")
                 else:
                     full_del.append(name)
             else:
-                _add_to_description(component_dict, ":green:`NEW`")
+                _add_to_description(component_dict, "|NEW|")
     model.math_documentation.build()
     for key in expr_del:
         model.math_documentation._instance._dataset[key].attrs["math_string"] = ""
@@ -192,11 +189,12 @@ def _ts_dfs() -> dict[str, pd.DataFrame]:
     return {"ts": ts}
 
 
-if __name__ == "__main__":
+def generate_math_docs():
     base_model_config = generate_model_config()
     base_model = generate_base_math_model(base_model_config)
+    base_model.math_documentation.write("_generated/math.md")
 
-    generate_custom_math_model(
+    custom_model = generate_custom_math_model(
         base_model,
         base_model_config,
         {
@@ -218,8 +216,10 @@ def _ts_dfs() -> dict[str, pd.DataFrame]:
                 },
             },
         },
-        "storage_inter_cluster",
     )
+
+    custom_model.math_documentation.write("_generated/math_storage_inter_cluster.md")
+
     # FIXME: Operate mode replaces variables with parameters, so we cannot show that the
     # variable has been deleted in the doc because we cannot build a variable with the same
     # name as another model component.
@@ -245,3 +245,7 @@ def _ts_dfs() -> dict[str, pd.DataFrame]:
     # generate_custom_math_model(
     #    base_model, base_model_config.copy(), {"model.custom_math": ["spores"]}, "spores"
     # )
+
+
+if __name__ == "__main__":
+    generate_math_docs()
diff --git a/requirements/mkdocs.yml b/requirements/mkdocs.yml
@@ -7,17 +7,15 @@ channels:
 dependencies:
   - python = 3.12
   - pip
+  - typing-extensions
+  - jsonschema2md = 1
+  - mkdocs
+  - mkdocs-material
+  - mkdocs-include-markdown-plugin
+  - mkdocs-gen-files
+  - mkdocs-jupyter
+  - mkdocs-click
+  - mkdocstrings
+  - mkdocstrings-python
   - pip:
-      - typing-extensions
-      - mkdocs
-      - mkdocs-include-markdown-plugin
-      - mkdocs-material
-      - mkdocstrings[python]
-      - mkdocs-gen-files
-      - mkdocs-jupyter
-      - mkdocs-click
-      - jsonschema2md == 1
-      - ruamel.yaml >= 0.17, < 0.18
-      - myst-parser == 1
-      - nbconvert >= 7.9, <8.0  # To generate HTML files from example notebooks
-      - "-e .."  # Install Calliope from source to build CLI docs
+      - "-e .."  # Calliope from source to build CLI docs