Development

Additional packages required for development

Attention

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

  • accessible-pygments

  • ipython

  • nbsphinx

  • pandoc

  • sphinx

  • sphinx_copybutton

  • sphinx_rtd_theme

  • sphinxcontrib-bibtex

In addition, pip-compile should be installed to update the requirements.txt for the next release.

Installing the packages

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

pip install accessible-pygments ipython nbsphinx pandoc sphinx sphinx_copybutton sphinx_rtd_theme sphinxcontrib-bibtex

python -m pip install pip-tools

Troubleshooting of installation issues

If you run into an error with pandoc, here is an answer that might help.
If you install pandoc with conda use:
conda install -c conda-forge pandoc

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

pip install jinja2==3.0.3

Updating the requirements.txt

To create the requirements.txt adjust the requirements.in file as needed in the folder docs.
Then navigate to the folder docs in the command line:
cd docs

and use the following command to automatically generate the new requirements.txt:

python3.9 -m piptools compile --output-file=requirements.txt requirements.in

Debugging switches

  • 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().

  • For debugging of pandas warnings or issues pd.options.mode.chained_assignment = None needs to be commented out.

Guidelines for code documentation

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# Tuple output & Single input
 2"""Description of the function...
 3
 4Args:
 5    - input1 (type): this is what input1 does
 6
 7Returns:
 8    tuple: Two tables (1) & (2)
 9        (1) pd.DataFrame: Table with charge mismatches
10        (2) pd.DataFrame: Table with formula mismatches
11"""
12
13# Single output with multiple possibilities & multiple inputs
14"""Description of the function...
15
16Args:
17    - input1 (type): this is what input1 does
18    - input2 (type): this is what input2 does
19    - input3 (type): this is what input3 does
20
21Returns:
22    (1) str:
23        - Return value 1
24        - Return value 2
25    (2) np.nan: Return value 3
26"""

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]:

More details for certain specifics can also be found here.