Api docs

[Peter9192]

• Generates API docs using mkdocstrings and mkdocs gen-pages, with slightly tweaked css
• Cleans up docstrings and makes them consistent accross datasets
• Auto-generate documentation of cli recipes similar to api generation
• Moves dataset recipes from tests to src/recipes/datasets

To do (in follow-up):

• Transpose documentation? Instead of (notebook/api/cli -> dataset) list like (dataset -> notebook/api/cli)
• Split up example recipes into individual datasets?

closes #149

[Peter9192]

https://github.com/pytest-dev/pytest/issues/4030

Running doctest as standalone behaves differently then running it through pytest:

# With doctest
python -m doctest -v src/springtime/datasets/NPNPhenor.py

# With pytest
pytest --doctest-modules src/springtime/datasets/NPNPhenor.py -v

Pytest correctly limits terminal width to 80 (the default value), whereas doctest let's it depend on terminal width. Thus, to get reproducible behaviour, the best option is to always run doctests through pytest. We have two options for the pandas repr behaviour:

• Option 1: Use pytest with default of 80 chars
• Option 2: Use pytest fixture to customize the printed dfs:

import pandas as pd
import pytest

@pytest.fixture(autouse=True, scope='session')
def pandas_terminal_width():
    pd.set_option('display.width', None)
    pd.set_option("display.max_columns", 7)
    pd.set_option("display.max_colwidth", 20)

The fixture needs to be in conftest.py in the same dir as the module that's being tested.

[Peter9192]

To get copy-pastable output from doctest: --doctest-report none https://docs.pytest.org/en/7.1.x/how-to/doctest.html#output-format

[Peter9192]

• Option 1: Use pytest with default of 80 chars

• Option 2: Use pytest fixture to customize the printed dfs:

Prefer option 1. More reproducible, and also keeps linter happy :-)

[Peter9192]

Code blocks formatted like this render nicely and also work with doctest:

class A:
    """
    Test

    Example:

        ```pycon
        >>> import time
        >>>
        >>> print('something')
        something

"""

Notes: 
- "Example" and "Examples" behave differently
- Whiteline at the end is necessary to break out of the output block
- "pycon" is syntax highlight for python console (https://pygments.org/docs/lexers/#pygments.lexers.python.PythonConsoleLexer)
- Modifying copy behaviour is possible but doesn't feel nice (https://github.com/squidfunk/mkdocs-material/issues/3647)

[Peter9192]

Having a hard time deciding whether to keep the example notebooks, doctests (or api docs in general), or both. There's signification overlap, but they also have their unique advantages.

• Notebooks are easier to work with locally to fix them if they're broken
• Notebooks have a nicer rendering of input vs output (doctest has these >>>, notebook have separate cells)
• Doctests serve both as examples with output illustration, and tests
• Notebooks could also be tested, e.g. with nbval, nbmake, or pytest-jupyter
• Doctests are closer to the source code
• In both cases, execution time is a challenge (and dependency on server calls)

[Peter9192]

Decided to keep both apidocs examples and notebooks.

[Peter9192]

Thanks for the review and adding your own suggestions! We now seem to have a new issue with displaying type inheritance:

I think the issue appeared only recently due to the latest release of griffe including https://github.com/mkdocstrings/griffe/pull/170.

ps in the screenshot also the internal links appear to have broken.

[Peter9192]

Okay, after a lot of tinkering I figured out that the order of the docstrings is what causes this weird behaviour.

Option 1: first own attributes, then inherited attributes --> repeated type of last own attribute in all inherited docstrings Option 2: first inherited attributes, then own attributes --> empty type for inherited docstrings

[sverhoeven]

Ok so you went with option 2, so we are not displaying incorrect data just empty types.

[Peter9192]

Indeed.