Doctest on all MD files

[BalzaniEdoardo]

Re-format the code in the md doc pages as a python interactive section, so that we can run doctest on it.

one way to run doctest on all md files is to add to the [testenv] in tox.ini:

[testenv]
#...other config
allowlist_externals = sh

# Run both pytest and coverage since pytest was initialized with the --cov option in the pyproject.toml
# while black, isort and flake8 are also i
commands =
    black --check src
    isort src --profile=black
    isort docs/how_to_guide --profile=black
    isort docs/background --profile=black
    isort docs/tutorials --profile=black
    flake8 --config={toxinidir}/tox.ini src
    pytest --doctest-modules src/nemos/
    pytest --cov=nemos --cov-config=pyproject.toml --cov-report=xml
    sh -c 'python -m doctest docs/dev*/*.md /docs/*.md'

Where the last commend uses the shell to expand the string pattern (won't work without).

We want to avoid the generated folders (which contains md, so i won't recommend "docs/**/*.md"). Also, there is no option for omit files/folders from the command line.

If we want to be generic we can add a script like this one:

import doctest
import glob
import sys
from pathlib import Path

# Expand wildcard patterns using glob
files = glob.glob("docs/**/*.md") + glob.glob("docs/*.md")

exclude_flds = ["generated", "reference"]

failed_doctest = False
# Run doctests for each file
for f in files:
    f = Path(f)
    if any(excl in f.parts for excl in exclude_flds):
        continue
    print(f"Running doctests for: {f}")
    failure_count, test_count = doctest.testfile(f, module_relative=False)

    if failure_count > 0:
        failed_doctest = True

if failed_doctest:
    print("One or more doctests failed. Exiting with error.", file=sys.stderr)
    sys.exit(1)

And then in the tox.ini run this script.