Documentation pipeline

[jcrozum]

This PR sets up the documentation pipeline and adds a linting to the CI.

Doctests are are added to the testing scripts. This will read examples in docstrings, run them, and verify that the output matches. Here is an example of how to format the docstrings to make sure doctest will recognize them (this example is from a different branch):

    """
    Succession diagram of a Boolean network.

    This encodes relationships between minimal trap spaces and can be used for
    attractor detection and control. Note that the succession diagram is
    expanded lazily, so it is not built until `build` or a similar method is
    called.

    Examples
    --------
    >>> import balm
    >>> sd = balm.SuccessionDiagram.from_bnet(\"""
    ...     A, B
    ...     B, A & C
    ...     C, !A | B
    ... \""")
    >>> print(sd.summary()) # not built yet!
    Succession Diagram with 1 nodes and depth 0.
    State order: A, B, C
    <BLANKLINE>
    Attractors in diagram:
    <BLANKLINE>
    >>> sd.build()
    >>> print(sd.summary()) # now it's built
    Succession Diagram with 3 nodes and depth 1.
    State order: A, B, C
    <BLANKLINE>
    Attractors in diagram:
    <BLANKLINE>
    minimal trap space 001
    ...................001
    <BLANKLINE>
    minimal trap space 111
    ...................111
    <BLANKLINE>
    """

Docs will be rebuilt upon pushes to main, and then deployed to the gh-pages branch (there is a sample there now; download the branch and open index.html in your browser to get a preview). Note that the autodocumentation relies on numpy-doc format docstrings and consistent type annotations. We are OK on type annotations, but the docstrings are not properly formatted in most cases. Various cross-linking features are available.

To build docs locally for testing:

pip install sphinx sphinx-toolbox pydata-sphinx-theme sphinx-copybutton sphinx-autoapi
sphinx-build -M html docs/source/ docs/build/

To run the lint checker locally,

pip install flake8 black
flake8 balm --ignore=E203,W503,C901 --select=C,E,F,W,B,B950 --max-line-length=127 --statistics --count --max-complexity=10
black . --check

Running black . will actually reformat the files (but I recommend making your IDE do this).

Also, I have (temporarily?) told flake8 to ignore the C901 restriction, which limits the complexity of functions, so the --max-complexity=10 doesn't really matter right now.

After this is merged, we can get to work writing good documentation for everything.

[github-actions[bot]]

Coverage Report

File	Stmts	Miss	Cover	Missing
balm
control.py	123	14	89%	48, 57, 61, 67, 81, 90–106, 329, 332, 345
interaction_graph_utils.py	54	5	91%	6–8, 47, 165–166
motif_avoidant.py	152	2	99%	25, 121
petri_net_translation.py	148	11	93%	18–22, 58, 94, 207–208, 232–233, 242, 346
space_utils.py	129	4	97%	25–27, 252, 278
succession_diagram.py	247	12	95%	6, 163, 177, 185, 188, 205–206, 312, 439, 627, 665, 700
symbolic_utils.py	26	3	88%	10–12, 44
trappist_core.py	183	30	84%	11–15, 45, 47, 82, 129, 195, 197, 199, 227–230, 234–236, 256–262, 320, 322, 352, 392, 394, 425, 454
balm/_sd_algorithms
compute_attractor_seeds.py	30	1	97%	8
expand_attractor_seeds.py	51	5	90%	6, 42, 97–102
expand_bfs.py	28	1	96%	6
expand_dfs.py	30	1	97%	6
expand_minimal_spaces.py	37	2	95%	6, 31
expand_source_SCCs.py	164	6	96%	19–21, 91, 101, 143, 287
expand_to_target.py	31	3	90%	6, 38, 43
TOTAL	1474	100	93%

Tests	Skipped	Failures	Errors	Time
364	0 :zzz:	0 :x:	0 :fire:	51.363s :stopwatch:

[jcrozum]

I forgot to mention that the actual web documentation can't go live until we make the repo public (or pay GH some money); that's why you'll need to download the gh-pages branch to view the docs manually for now.

[jcrozum]

@daemontus @giang-trinh @kyuhyongpark No need to review this if you don't want to (most changes are just the linter doing its thing). Let me know if you want any changes to the GitHub workflows though.

[jcrozum]

I also discussed this with @kyuhyongpark last Friday, so I am going to merge this.