Development

Development installation

Attention

The following packages need to be installed to be able to add content to the refineGEMs documentation.

  • sphinx

  • nbsphinx

  • sphinx_rtd_theme

  • pandoc

  • ipython

  • sphinxcontrib-bibtex

You can install the packages via pip to your local environment:

pip install sphinx nbsphinx sphinx_rtd_theme pandoc ipython sphinxcontrib-bibtex

If you run into an error with jinja2, just switch to version 3.0.3:

pip install jinja2==3.0.3

Development notes

You can enable debug logging by replacing level=logging.INFO with level=logging.DEBUG.

If you want your print message to show in the log file, replace the `print() statement by logging.info().

Documentation notes

We use the autoDocstring extension (njpwerner.autodocstring) for vscode with the google format to generate function docstrings. To ensure a nice looking sphinx documentation, we add - to all variables that are passed as Args. And tuple returns are written as follows:

 1"""Description of the function...
 2
 3Args:
 4    - input1 (type): this is what input1 does
 5
 6Returns:
 7    tuple: Two tables (1) & (2)
 8        (1) pd.DataFrame: Table with charge mismatches
 9        (2) pd.DataFrame: Table with formula mismatches
10"""

We are also trying to make input and return types explicit by declaring those in the function header:

1def my_func(input1: int, input2: str, input3: Model) -> tuple[str, int]: