# Scientific Documentation in ICON4Py

## Meeting 5.10.24 at OAT
@jcanton @nfarabullini @mluz @egparedes

## Ideas
- [x] Use latex macros (`newcommand`) from a preamble file to simplify the written form of the equations in the docstrings, and then inject/pass the macros to the sphinx latex processor.
- [x] In the caller site there should be a link to the docstring of the called stencil.
- [ ] Somebody needs to fix gt4py decorators for autodoc to work @egparedes ?
- [x] Automatically get variable types
- [x] Move from docstrings to comment blocks
- [x] Remove all notion of docstrings in icon4py_sphinx.py (since now it doesn't apply)
- [x] Move all the config options to conf.py and pass (a dictionary?) to the latex macros processor and fullmethoddocumenter such that conf.py is purely declarative
- [ ] Make a help page with a description of the symbols (need to find a way to get the LaTeX macros into it)
- [ ] The docs should be in a githook and automatically rendered on github/readthedocs
- [ ] Make the offset provider figures as mouse hover pop-ups (https://sphinx-hoverxref.readthedocs.io/en/latest/index.html)
- [ ] Improve the offset provider figures such that you don't have to copy-paste drawing code but you can combine them (c2e <- c2e2c)
- [ ] Move from matplotlib png figures to svg ones (https://lukaszmentel.com/blog/svg-wallpapers-with-python/index.html, https://svgwrite.readthedocs.io/en/latest/index.html)
- [ ] Make a dictionary/map of output variable names to the stencil that computes them such that when they are later found as inputs the `input` variable name can become a hyperlink to the stencil that computes it (and has it in output)

## Long term ideas
- [ ] Add documentation for all the interpolation/gradient/div coefficients (how they are computed and where with sketches of the mesh)
- [ ] Move the equations inside the field_operators (using appropriate symbols) and only have a dictionary mapping symbols in the big methods (predictor/corrector, etc) that maps to the equation in the (sci)docstring of the field_operator (TODO at The-Big-Refactoring-TM)
- [ ] Find a way and place to add the other equations @jcanton is working on (closer to icon tutorial)
- [ ] Use a custom language server to inline the rendered documentation in the source code

## Sample

### Source

"""
Outputs:
    z_exner_ex_pr: $$
        \exnerprime{\ntilde}{\k} = (1 + \gamma) \exnerprime{\ntilde}{\k} - \gamma \exnerprime{\n-1}{\k}
    $$
        Compute the temporal extrapolation of perturbed exner function
        at full levels (cell center) using the time backward scheme
        (page 74 in [ICON Tutorial 2023](a-link-that-works)) for
        horizontal momentum equations. Note that it has nlev+1 levels.
        This last level is underground and set to zero.

    exner_pr: $$ \pi_k^{\prime n-1} = \pi_k^{\prime n} $$
        Store perturbed exner function at full levels of current time step.
 
Inputs:
    $\pi_k^{\prime\tilde{n}}$: bla.foo.bar
    $\gamma$: exner_exfac
"""
nhsolve_prog._predictor_stencils_2_3(
    exner_exfac,
    exner,
    exner_ref_mc,
    exner_pr,
    z_exner_ex_pr,
    k_field,
    nlev,
    out=(z_exner_ex_pr, exner_pr),
    domain={
        dims.CellDim: (horizontal_start, horizontal_end),
        dims.KDim: (vertical_start, vertical_end),
    },
)

### Generated documentation

-------------------------------

### [predictor_stencils_2_3](docstring_of_predictor_stencils_2_3)

**Outputs**:
- **z_exner_ex_pr: *Field[C, K]***
$$
\pi_{k}^{\prime\tilde{n}} = (1 + \gamma) \pi_k^{\prime n} - \gamma \pi_k^{\prime n-1}, \qquad k \in [0, \mathrm{nlev})
$$
Compute the temporal extrapolation of perturbed exner function using the time backward scheme (page 74 in [ICON Tutorial 2023](a-link-that-works)) for horizontal momentum equations.

- **exner_pr: *Field[C, K]***
$$
\pi_k^{\prime n-1} = \pi_k^{\prime n}
$$
Store perturbed exner function at full levels of current time step.

**Inputs:**
:::spoiler
- $\pi_k^{\prime\tilde{n}}$ -> bla.foo.bar
- $\gamma$ -> exner_exfac
:::

**Source:**
:::spoiler

nhsolve_prog.predictor_stencils_2_3(
    exner_exfac=self.metric_state_nonhydro.exner_exfac,
    exner=prognostic_state[nnow].exner,
    exner_ref_mc=self.metric_state_nonhydro.exner_ref_mc,
    exner_pr=diagnostic_state_nh.exner_pr,
    z_exner_ex_pr=self.z_exner_ex_pr,
    horizontal_start=self._start_cell_lateral_boundary_level_3,
    horizontal_end=self._end_cell_halo,
    k_field=self.k_field,
    nlev=self.grid.num_levels,
    vertical_start=0,
    vertical_end=self.grid.num_levels + 1,
    offset_provider={},
)

:::
----------------------------