Minor docs fixes (#557)

* Fix ref to math_documentation calls * Update missing changelog entry; add note on tabs * Update example tabular data to markdown tables * Fix typo in troubleshooting --------- Co-authored-by: Bryn Pickering <17178478+brynpickering@users.noreply.github.com>
calliope-project · Feb 14, 2024 · cc0b953 · cc0b953
1 parent 0e12b05
commit cc0b953
Show file tree

Hide file tree

Showing 5 changed files with 68 additions and 67 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,8 @@ These default values ensure that `NaN` doesn't creep into the built optimisation
 |fixed| Timeseries clustering file can be a non-ISO standard date format.
 Both the index and the values of the timeseries (both being date strings) should be in the user-defined `config.init.time_format`.
 
+|fixed| the decision variable `purchased_units` is linked to `flow_cap` even if neither of the parameters `flow_cap_min` or `flow_cap_max` have been defined by the user.
+
 |changed| `inbuilt` math -> `pre-defined` math and `custom` math -> `pre-defined` math in the documentation.
 
 ## 0.7.0.dev2 (2024-01-26)

diff --git a/docs/creating/data_sources.md b/docs/creating/data_sources.md
@@ -33,12 +33,10 @@ In this section we will show some examples of loading data and provide the equiv
 
     Data in file:
 
-    ```
-    ,
-    2005-01-01 12:00:00,15
-    2005-01-01 13:00:00,5
-    ...
-    ```
+    | timesteps           |    |
+    | ------------------: | :- |
+    | 2005-01-01 12:00:00 | 15 |
+    | 2005-01-01 13:00:00 | 5  |
 
     YAML definition to load data:
 
@@ -76,17 +74,21 @@ In this section we will show some examples of loading data and provide the equiv
 
     Data in file:
 
-    ```shell
-    tech1,base_tech,supply  # (1)!
-    tech1,flow_cap_max,100
-    tech1,flow_out_eff,0.1
-    tech1,area_use_max,500
-    tech1,area_use_per_flow_cap,7
-    tech2,base_tech,demand
-    tech3,base_tech,storage
-    tech3,storage_cap_max,200
-    tech3,flow_cap_max,100
-    ```
+    <div class="annotate" markdown>
+
+    |       |                       |             |
+    | ----: | --------------------: | :---------- |
+    | tech1 | base_tech             | supply  (1) |
+    | tech1 | flow_cap_max          | 100         |
+    | tech1 | flow_out_eff          | 0.1         |
+    | tech1 | area_use_max          | 500         |
+    | tech1 | area_use_per_flow_cap | 7           |
+    | tech2 | base_tech             | demand      |
+    | tech3 | base_tech             | storage     |
+    | tech3 | storage_cap_max       | 200         |
+    | tech3 | flow_cap_max          | 100         |
+
+    </div>
 
     1. Unlike the previous example, we do not have a "header" row with column names in this file.
     We start directly with defining data.
@@ -125,15 +127,15 @@ In this section we will show some examples of loading data and provide the equiv
 
     Data in file:
 
-    ```
-    tech1,cost_flow_cap,100
-    tech1,cost_area_use,50
-    tech1,cost_flow_out,0.2
-    tech1,cost_interest_rate,0.1
-    tech3,cost_flow_cap,20
-    tech3,cost_storage_cap,150
-    tech3,cost_interest_rate,0.1
-    ```
+    |       |                    |      |
+    | ----: | -----------------: | :--- |
+    | tech1 | cost_flow_cap      | 100  |
+    | tech1 | cost_area_use      | 50   |
+    | tech1 | cost_flow_out      | 0.2  |
+    | tech1 | cost_interest_rate | 0.1  |
+    | tech3 | cost_flow_cap      | 20   |
+    | tech3 | cost_storage_cap   | 150  |
+    | tech3 | cost_interest_rate | 0.1  |
 
     YAML definition to load data:
 
@@ -195,12 +197,11 @@ For instance:
 
 Data in file:
 
-```
-,,node1,node2,node3
-tech1,parameter1,100,200,300
-tech2,parameter1,0.1,0.3,0.5
-tech3,parameter1,20,45,50
-```
+|       |            | node1 | node2 | node3 |
+| ----: | ---------: | :---- | :---- | :---- |
+| tech1 | parameter1 | 100   | 200   | 300   |
+| tech2 | parameter1 | 0.1   | 0.3   | 0.5   |
+| tech3 | parameter1 | 20    | 45    | 50    |
 
 YAML definition to load only data from nodes 1 and 2:
 
@@ -218,12 +219,11 @@ You may also want to store scenarios in your file.
 When you load in the data, you can select your scenario.
 You will also need to `drop` the dimension so that it doesn't appear in the final calliope model dataset:
 
-```
-,,scenario1,scenario2
-tech1,parameter1,100,200
-tech2,parameter1,0.1,0.3
-tech3,parameter1,20,45
-```
+|       |            | scenario1 | scenario2 |
+| ----: | ---------: | :-------- | :-------- |
+| tech1 | parameter1 | 100       | 200       |
+| tech2 | parameter1 | 0.1       | 0.3       |
+| tech3 | parameter1 | 20        | 45        |
 
 YAML definition to load only data from scenario 1:
 
@@ -257,12 +257,11 @@ For example, to define costs for the parameter `cost_flow_cap`:
 
 === "Without `add_dimensions`"
 
-    ```
-    ,,,node1,node2,node3
-    tech1,monetary,cost_flow_cap,100,200,300
-    tech2,monetary,cost_flow_cap,0.1,0.3,0.5
-    tech3,monetary,cost_flow_cap,20,45,50
-    ```
+    |       |          |               | node1 | node2 | node3 |
+    | ----: | -------: | ------------: | :---- | :---- | :---- |
+    | tech1 | monetary | cost_flow_cap | 100   | 200   | 300   |
+    | tech2 | monetary | cost_flow_cap | 0.1   | 0.3   | 0.5   |
+    | tech3 | monetary | cost_flow_cap | 20    | 45    | 50    |
 
     ```yaml
     data_sources:
@@ -274,12 +273,11 @@ For example, to define costs for the parameter `cost_flow_cap`:
 
 === "With `add_dimensions`"
 
-    ```
-    ,node1,node2,node3
-    tech1,100,200,300
-    tech2,0.1,0.3,0.5
-    tech3,20,45,50
-    ```
+    |       | node1 | node2 | node3 |
+    | ----: | :---- | :---- | :---- |
+    | tech1 | 100   | 200   | 300   |
+    | tech2 | 0.1   | 0.3   | 0.5   |
+    | tech3 | 20    | 45    | 50    |
 
     ```yaml
     data_sources:
@@ -296,14 +294,10 @@ Or to define the same timeseries source data for two technologies at different n
 
 === "Without `add_dimensions`"
 
-    ```
-    ,node1,node2
-    ,tech1,tech2
-    ,source_use_max,source_use_max
-    2005-01-01 00:00,100,100
-    2005-01-01 00:00,200,200
-    ...
-    ```
+    |                  | node1<br>tech1<br>source_use_max | node2<br>tech2<br>source_use_max |
+    | ---------------: | :--------------------------------| :------------------------------- |
+    | 2005-01-01 00:00 | 100                              | 200                              |
+    | 2005-01-01 01:00 | 200                              | 200                              |
 
     ```yaml
     data_sources:
@@ -317,11 +311,10 @@ Or to define the same timeseries source data for two technologies at different n
 
 === "With `add_dimensions`"
 
-    ```
-    2005-01-01 00:00,100
-    2005-01-01 00:00,200
-    ...
-    ```
+    |                  |     |
+    | ---------------: | :-- |
+    | 2005-01-01 00:00 | 100 |
+    | 2005-01-01 01:00 | 200 |
 
     ```yaml
     data_sources:

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -154,7 +154,7 @@ gurobi_cl ResultFile=result.ilp my_saved_model.lp
 !!! info "See also"
     More detail on this Gurobi functionality is available in the [official Gurobi documentation](https://www.gurobi.com/documentation/current/refman/solving_a_model2.html).
 
-To deal with numerically unstable models, try setting `#!yaml onfig.solve.solver_options: {Presolve: 0}`, as large numeric ranges can cause the pre-solver to generate an [infeasible or numerically unstable model](https://www.gurobi.com/documentation/current/refman/numerics_why_scaling_and_g.html).
+To deal with numerically unstable models, try setting `#!yaml config.solve.solver_options: {Presolve: 0}`, as large numeric ranges can cause the pre-solver to generate an [infeasible or numerically unstable model](https://www.gurobi.com/documentation/current/refman/numerics_why_scaling_and_g.html).
 The [Gurobi Guidelines for Numerical Issues](https://www.gurobi.com/documentation/current/refman/numerics_gurobi_guidelines.html) give detailed guidance for strategies to address numerically difficult optimisation problems.
 
 ### Using the CPLEX solver
@@ -222,4 +222,4 @@ There are private attributes of the Calliope `Model` object that you can access
     If using Calliope in a Python session, we recommend reading up on the [Python debugger](https://docs.python.org/3/library/pdb.html) and making use of the [`%debug` magic](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-debug).
 
 !!! info "See also"
-    We go into the details of the Calliope model in [one of our tutorial notebooks][the-calliope-model-and-backend-objects].
+    We go into the details of the Calliope model in [one of our tutorial notebooks][the-calliope-model-and-backend-objects].
diff --git a/docs/user_defined_math/customise.md b/docs/user_defined_math/customise.md
@@ -39,9 +39,14 @@ To write a LaTeX, reStructuredText, or Markdown file that includes only the math
 
 ```python
 model = calliope.Model("path/to/model.yaml")
-model.build_math_documentation(include="valid")
-model.write_math_documentation(filename="path/to/output/file.[tex|rst|md]")
+model.math_documentation.build(include="valid")
+model.math_documentation.write(filename="path/to/output/file.[tex|rst|md]")
 ```
 
 You can then convert this to a PDF or HTML page using your renderer of choice.
 We recommend you only use HTML as the equations can become too long for a PDF page.
+
+!!! note
+
+    You can add the tabs to flip between rich-text math and the input YAML snippet in your math documentation by using the `mkdocs_tabbed` argument in `model.math_documentation.write`.
+    We use this functionality in our [pre-defined math](../pre_defined_math/index.md).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -68,6 +68,7 @@ markdown_extensions:
   - md_in_html
   - mkdocs-click
   - def_list
+  - tables
   - toc:
       permalink: "¶"
       toc_depth: 3