Autogenerate api docs

.github/workflows/process.yml

@@ -178,7 +178,6 @@ jobs:
         uses: Fusion-Power-Plant-Framework/fppf-actions/setup-hatch@main
         with:
           python-version: ${{ env.python-version }}
-      - run: hatch run python scripts/vardes.py
       - run: git config --global --add safe.directory '*'
       - name: Download STF_TF.json files
         uses: actions/download-artifact@v4

.gitignore

@@ -46,10 +46,8 @@ process/io/python_fortran_dicts.json
 fortran.py
 .coverage
 dist/*
-documentation/io/vardes.md
 lcov_results/
 env/
-env_process/
 .venv
 *.DAT
 !scenario_examples/*/*.DAT

documentation/scripts/gen_api_ref.py

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2023-present The Bluemira Developers <https://github.com/Fusion-Power-Plant-Framework/bluemira>
+#
+# SPDX-License-Identifier: LGPL-2.1-or-later
+"""Generate the API reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+from mkdocs_gen_files.nav import Nav
+
+nav = Nav()
+
+root = Path(__file__).parent.parent.parent
+package_name = "process"
+src = root / package_name
+reference = Path("source", "reference")
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(root).with_suffix("")
+    doc_path = path.relative_to(root).with_suffix(".md")
+    full_doc_path = Path(reference, doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] in {"__init__", "__main__", "_version"}:
+        continue
+
+    p = ".".join(parts)
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        fd.write(f"::: {p}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open(Path(reference, "overview.md"), "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

documentation/scripts/plotting_scripts/menard_beta_norm_plot.py

@@ -11,13 +11,13 @@
     y_range=(2, 8),
     width=400,
     height=400,
-    title="Menard Normalized Beta Limit",
+    title="Menard Normalised Beta Limit",
 )
 plot.xaxis.axis_label = r"Aspect ratio, \  $$[A]$$"
-plot.yaxis.axis_label = r"Normalized beta limit, \  $$[\beta_N]$$"
+plot.yaxis.axis_label = r"Normalised beta limit, \  $$[\beta_N]$$"
 
 plot.line("x", "y", source=source, line_width=3, line_alpha=0.6)
 
 # Save the plot as HTML
-output_file("menard_beta_norm.html", title="Menard Normalized Beta Limit")
+output_file("menard_beta_norm.html", title="Menard Normalised Beta Limit")
 save(plot)

documentation/scripts/plotting_scripts/original_beta_norm_plot.py

@@ -11,13 +11,13 @@
     y_range=(2, 15),
     width=400,
     height=400,
-    title="Original Normalized Beta Limit",
+    title="Original Normalised Beta Limit",
 )
 plot.xaxis.axis_label = r"Aspect ratio, \  $$[A]$$"
-plot.yaxis.axis_label = r"Normalized beta limit, \  $$[\beta_N]$$"
+plot.yaxis.axis_label = r"Normalised beta limit, \  $$[\beta_N]$$"
 
 plot.line("x", "y", source=source, line_width=3, line_alpha=0.6)
 
 # Save the plot as HTML
-output_file("original_beta_norm.html", title="Original Normalized Beta Limit")
+output_file("original_beta_norm.html", title="Original Normalised Beta Limit")
 save(plot)

documentation/scripts/plotting_scripts/profile_hastie_current.py

@@ -16,7 +16,7 @@
     height=400,
     title="PROCESS vs Hastie Current Profile",
 )
-plot.xaxis.axis_label = "Normalized Plasma Radius"
+plot.xaxis.axis_label = "Normalised Plasma Radius"
 plot.yaxis.axis_label = "Current Density, J"
 
 plot.line(

documentation/scripts/plotting_scripts/profile_parabolic_plot.py

@@ -15,7 +15,7 @@
     height=400,
     title="Parabolic Profile | L-mode",
 )
-plot.xaxis.axis_label = r"Normalized Radius, $$ \rho $$"
+plot.xaxis.axis_label = r"Normalised Radius, $$ \rho $$"
 plot.yaxis.axis_label = r"Density, $$n_e$$"
 
 plot.line("x", "y", source=source, line_width=3, line_alpha=0.6)

documentation/scripts/plotting_scripts/profile_pedestal_plot.py

@@ -29,7 +29,7 @@
     height=400,
     title="Pedestal Profile | H-mode",
 )
-plot.xaxis.axis_label = r"Normalized Radius, $$ \rho $$"
+plot.xaxis.axis_label = r"Normalised Radius, $$ \rho $$"
 plot.yaxis.axis_label = r"Density, $$n_e$$"
 
 plot.line("x", "y", source=source, line_width=3, line_alpha=0.6)

documentation/cost-models/cost-models.md → documentation/source/cost-models/cost-models.md

@@ -4,7 +4,7 @@ Two cost models are available, determined by the switch `cost_model`.
 
 ## 1990 cost model (`cost_model = 0`)
 
-This combines methods[^1] used in the TETRA code [^2] and the Generomak[^3] scheme. The costs are split into accounting categories[^4]. The best references for the algorithms used are[^5], and source file `costs.f90` in the code itself. The majority of the costed items have a unit cost associated with them. These values scale with (for example) power output, volume, component mass etc., and many are avaiable to be changed via the input file. All costs and their algorithms correspond to 1990 dollars.
+This combines methods[^1] used in the TETRA code [^2] and the Generomak[^3] scheme. The costs are split into accounting categories[^4]. The best references for the algorithms used are[^5], and source file `costs.f90` in the code itself. The majority of the costed items have a unit cost associated with them. These values scale with (for example) power output, volume, component mass etc., and many are available to be changed via the input file. All costs and their algorithms correspond to 1990 dollars.
 
 The unit costs of the components of the fusion power core are relevant to "first-of-a-kind" items. That is to say, the items are assumed to be relatively expensive to build as they are effectively prototypes and specialised tools and machines have perhaps been made specially to create them. However, if a "production line" has been set up, and R & D progress has allowed more experience to be gained in constructing the power core components, the cost will be reduced as a result. Variable `fkind` may be used to multiply the raw unit costs of the fusion power core items (by a factor less than one) to simulate this cost reduction for an *N<sup>th</sup>*-of-a-kind device. In other systems studies of fusion power plants[^6], values for this multiplier have ranged from 0.5 to 0.8.
 
@@ -14,7 +14,7 @@ The first wall, blanket, divertor, centrepost (if present) and current drive sys
 
 If the switch `ireactor = 0`, no cost of electricity calculation is performed. If `ireactor = 1`, then the cost of electricity is evaluated, with the value quoted in units of $/MWh.
 
-The net electric power is calculated in routine `POWER` It is possible that the net electric power can become negative due to a high recirculating power. Switch `ipnet` determines whether the net electric power is scaled to always reamin positive (`ipnet = 0`, or whether it is allowed to become negative (`ipnet = 1`), in which case no cost of electricity calculation is performed.
+The net electric power is calculated in routine `POWER` It is possible that the net electric power can become negative due to a high recirculating power. Switch `ipnet` determines whether the net electric power is scaled to always remain positive (`ipnet = 0`, or whether it is allowed to become negative (`ipnet = 1`), in which case no cost of electricity calculation is performed.
 
 ## 2015 Kovari model (`cost_model = 1`)
 

documentation/development/add-vars.md → documentation/source/development/add-vars.md

@@ -58,7 +58,7 @@ To add a `PROCESS` iteration variable please follow the steps below, in addition
 1. The parameter `ipnvars` in module `numerics` of `numerics.f90` will normally be greater than the actual number of iteration variables, and does not need to be changed.
 2. Append a new iteration number key to the end of the `ITERATION_VARIABLES` dictionary  in `iteration_variables.py`. The associated variable is the corresponding key value.
 3. Set the variable origin file and then the associated lower and upper bounds
-4. Update the `lablxc` derscription in `numerics.f90`.
+4. Update the `lablxc` description in `numerics.f90`.
 
 It should be noted that iteration variables must not be reset elsewhere in the
 code. That is, they may only be assigned new values when originally
@@ -110,7 +110,7 @@ After following the instruction to add an input variable, you can make the varia
 
 2. Add a short description of the new scanning variable in the `nsweep` comment in `scan_variables.py`, alongside its identification number.
 
-3. Update the `SCAN_VARIABLES` dictionary in the `scan.py` file by adding a new case statement connecting the variable to the scan integer switch, the variable name and a short description. 
+3. Update the `ScanVariables` enum in the `scan.py` file by adding a new case statement connecting the variable to the scan integer switch, the variable name and a short description.
 
 4. Add a comment in the corresponding variable file in the data_structure directory, eg, `data_structure/[XX]_variables.py`, to add the variable description indicating the scan switch number.
 
@@ -130,12 +130,12 @@ After following the instruction to add an input variable, you can make the varia
 `SCAN_VARIABLES` case example:
 
 ```python
-  SCAN_VARIABLES = {
-    1: ScanVariable("aspect", "Aspect_ratio"),
-    2: ScanVariable("pflux_div_heat_load_max_mw", "Div_heat_limit_(MW/m2)"),
+  class ScanVariables(Enum):
+    aspect: ScanVariable("aspect", "Aspect_ratio", 1),
+    pflux_div_heat_load_max_mw: ScanVariable("pflux_div_heat_load_max_mw", "Div_heat_limit_(MW/m2)", 2),
     ...
-    54: ScanVariable("Bc2(0K)", "GL_NbTi Bc2(0K)"),
-    55: ScanVariable("dr_shld_inboard", "Inboard neutronic shield"),
+    Bc2_0K: ScanVariable("Bc2(0K)", "GL_NbTi Bc2(0K)", 54),
+    dr_shld_inboard : ScanVariable("dr_shld_inboard", "Inboard neutronic shield", 55),
 ```
 
 ---------------
@@ -170,4 +170,4 @@ def my_constraint_function():
   value = ...
   error = ...
   return ConstraintResult(normalised_residual, value, error)
-```
+```

documentation/development/debugging.md → documentation/source/development/debugging.md

@@ -3,7 +3,7 @@
 Debugging allows you stop a program mid-execution (called 'breaking') and explore the current state (e.g. print the current value of variables or attributes). In Python, this is done using `pdb` which comes as-standard with Python. 
 
 First, you must decide where in the code you would like to break. When debugging, a useful way to 
-decide is to look at the terminal for where the error may have occured and break there. To insert a 
+decide is to look at the terminal for where the error may have occurred and break there. To insert a 
 breakpoint in the code, insert the following code where you want the code to break:
 
 ```python

documentation/development/standards.md → documentation/source/development/standards.md

@@ -8,7 +8,7 @@ You can check if your code meets the `ruff` standards by running:
 2. `pre-commit run --all-files`
 
 !!! Info "ruff automatic fixes"
-    Many problems that `ruff` can detect it can also safely fix. Simply run `ruff check --fix` and it will try and automatically fix the mistakes, rewritting your source code. 
+    Many problems that `ruff` can detect it can also safely fix. Simply run `ruff check --fix` and it will try and automatically fix the mistakes, rewriting your source code. 
 
 
 --------------------
@@ -601,7 +601,7 @@ ii
 | `b_t_onaxis`  | Toroidal field on-axis | T |
 | `b_t_max`     | Max toroidal field | T |
 | `nd_electron_vol` | Volume average electron density | m-3 |
-| `temp_electron_vol_eV` | Volume avgerage electron temperature | eV |
+| `temp_electron_vol_eV` | Volume average electron temperature | eV |
 | `m_steel` | Mass of steel | kg |
 | `m_steel_tonne` | Mass of steel | tonne |
 | `e_neutron_eV` | Energy of neutron | eV |
@@ -634,26 +634,39 @@ The docstring style is that of the [Sphinx type](https://www.sphinx-doc.org/en/m
 If writing in new Python functions please use the docstring template below.
 
 ```python
-def function_name(param1, param2):
+def function_name(param1: Any, param2: Any) -> Any:
     """
     Brief description of what the function does.
 
     Detailed description of the function. This can include information about the algorithm,
     any important notes, and other relevant details.
 
-    :param type param1: Description of the first parameter.
-    :param type param2: Description of the second parameter.
-    :returns: Description of the return value.
-    :rtype: return_type
-    :raises ExceptionType: Description of the exception raised (if any).
-
-    :notes:
-        - Additional notes about the function.
-        - Any important considerations or caveats.
-
-    :references:
-        - Reference 1: Description of the reference.
-        - Reference 2: Description of the reference.
+    Parameters
+    ----------
+    param1:
+        Description of the first parameter.
+    param2:
+        Description of the second parameter.
+
+    Returns
+    -------
+    :
+        Description of the return value.
+
+    Raises
+    ------
+    ExceptionType
+        Description of the exception raised (if any).
+
+    Notes
+    -----
+    - Additional notes about the function.
+    - Any important considerations or caveats.
+
+    References
+    ----------
+    - Reference 1: Description of the reference.
+    - Reference 2: Description of the reference.
     """
 ```
 
@@ -700,4 +713,4 @@ class ExampleClass:
 
 - Use inline comments sparingly.
 
-- Comments above apply to code below.
+- Comments above apply to code below.

documentation/eng-models/blanket_overview.md → documentation/source/eng-models/blanket_overview.md

@@ -48,7 +48,7 @@ Using the Reynolds number we calculate the Darcy friction factor using the Haala
 
 For the radius of the pipe bend we assume it to be 3 times the radius of the coolant channel.
 
-The elbow coefficients for the 90 and 180 degree bends $\left(f_{\text{90,elbow}}, f_{\text{180,elbow}}\right)$ are clalculated via [`elbow_coeff()`](#pipe-bend-elbow-coefficient--elbow_coeff).
+The elbow coefficients for the 90 and 180 degree bends $\left(f_{\text{90,elbow}}, f_{\text{180,elbow}}\right)$ are calculated via [`elbow_coeff()`](#pipe-bend-elbow-coefficient--elbow_coeff).
 
 The pressure drop for the straights along the entire pipe length is the same as above:
 

documentation/eng-models/central-solenoid.md → documentation/source/eng-models/central-solenoid.md

@@ -80,7 +80,7 @@ $$
 
 where $\alpha = \frac{r_{\text{CS,outer}}}{r_{\text{CS,inner}}}$, is the ratio of the outer and inner radii of the solenoid and $\beta = \frac{z_{\text{CS,half}}}{r_{\text{CS,outer}}}$, is the ratio of the solenoid half height to its inboard radius.
 
-The peak field at the bore of the central solenoid will not be the same as that felt by the conductors inside the structures. We require to know the peak field on the conductor if we are to design a superconducting central solenoid that has enough margin. Fits to data[^1] for different ranges of $\beta$ have been calulated as follows:
+The peak field at the bore of the central solenoid will not be the same as that felt by the conductors inside the structures. We require to know the peak field on the conductor if we are to design a superconducting central solenoid that has enough margin. Fits to data[^1] for different ranges of $\beta$ have been calculated as follows:
 
 - $\beta > 3.0$
 

documentation/eng-models/divertor.md → documentation/source/eng-models/divertor.md

@@ -95,7 +95,7 @@ $$
 
     The main assumption of the Peng gaseous divertor model is that the power radiated to the divertor is equally radiated in the divertor box across all three surfaces. This may not truly be the case in reality.
 
-The interactive graph below can be used to investigate how changing the key prameters changes the divertor configuration. The grey box represents the first wall, the far right red line represents the right hand edge of the divertor region ($r_{\text{outer}}$), the far left red line represents the left hand edge of the divertor region ($r_{\text{inner}}$) and the blue line represents the bottom of the divertor region ($\Delta z_{\text{plasma,div}}$).
+The interactive graph below can be used to investigate how changing the key parameters changes the divertor configuration. The grey box represents the first wall, the far right red line represents the right hand edge of the divertor region ($r_{\text{outer}}$), the far left red line represents the left hand edge of the divertor region ($r_{\text{inner}}$) and the blue line represents the bottom of the divertor region ($\Delta z_{\text{plasma,div}}$).
 
 -------------