Scidoc processor

The scidoc processor is an extension of sphinx’s autodoc documenter with some additions tailored to documenting ICON4Py long methods.

Using the scidoc processor in the sphinx documentation

Using the processor to document a class/method/function is done in the same way as sphinx’s autodoc, just using the autoscidoc keyword instead of autodoc, and is as easy as:

.. autoscidoc:: icon4py.model.atmosphere.dycore.solve_nonhydro.SolveNonhydro.run_predictor_step
   :no-index:

The example above runs the processor over the run_predictor_step method, the results of which can be found at Dycore numerical documentation (solve nonhydro).

Adding scidoc documentation to the code

The processor is designed in such a way that the source code needs just a few comment lines for a fully featured documentation page to be automatically generated.

As an example from the dycore, the comment block describing the call to the stencil _compute_horizontal_gradient_of_exner_pressure_for_flat_coordinates results in the web page section displayed in the frame below (and part of the Dycore numerical documentation (solve nonhydro) page).

All that is required are the Outputs and Inputs sections, listing the variables processed by the stencil. A few lines can (should) be added describing the numerical operations resulting in the ouput variables, using the names in the namespace of the calling method (not of the stencil which could be a generic a+b operation).

The processor takes care of:

generating a title that is also a hyperlink to the stencil documentation,
parsing the equations with LaTeX syntax and macros,
inferring and adding variable types to both inputs and outputs,
generating and including figures describing the offset providers used in the stencil,
including the source code of the stencil call

# scidoc:
# Outputs:
#  - z_gradh_exner :
#     $$
#     \exnerprimegradh{\ntilde}{\e}{\k} = \Cgrad \Gradn_{\offProv{e2c}} \exnerprime{\ntilde}{\c}{\k}, \quad \k \in [0, \nflatlev)
#     $$
#     Compute the horizontal gradient (at constant height) of the
#     temporal extrapolation of perturbed exner function on flat levels,
#     unaffected by the terrain following deformation.
#
# Inputs:
#  - $\exnerprime{\ntilde}{\c}{\k}$ : z_exner_ex_pr
#  - $\Cgrad$ : inverse_dual_edge_lengths
#
self._compute_horizontal_gradient_of_exner_pressure_for_flat_coordinates(
    ...
)