Standardize documentation

[jcrozum]

We need to make sure the docstrings all describe inputs, outputs, etc. in a standard format, ideally with examples. Unless anyone objects, I'll use the "numpy docs" format; this is what pystablemotifs uses and it's pretty common in the scientific Python space. Then, we can run pdoc or similar to generate the api reference and use something like pydoc to test the docstring examples. It's likely that we can add this step to the CI. I will take a look at how polars does it; I've been contributing to their documentation and the process works very smoothly. We should also make some basic usage examples to help new users get started. In summary, here are the action items:

• Convert existing docstrings into the numpy docs format if they aren't already using it.
• Write new docstrings for methods that are missing them.
• Add examples to docstrings.
• Automatically generate api reference from docstrings using pdoc (or something like it).
• Add a step to the CI to generate the api reference.
• Add a step to the CI to test the docstring examples.
• Write one or more simple "getting started" tutorials.

[jcrozum]

Note: decided to use sphinx to generate the documentation and doctest to test the documentation examples. Might switch to using the doctesting built into sphinx if it can handle tutorial examples that aren't inside docstrings.

Working on integrating this into the CI.

[jcrozum]

The documentation pipeline has been merged into main. Next step is to start making nicer docstrings for everything.

[jcrozum]

I added an example docstring here: https://github.com/jcrozum/balm/blob/drivers-docs/balm/drivers.py that showcases the expected syntax for cross-linking, descriptions, parameters, return values, and examples.

[jcrozum]

@daemontus I am working my way through the docs and I have a couple of questions for you.

1. In some of the functions, we use ctx to refer to a "context", but the type of this variable is sometimes AsynchronousGraph, sometimes SymbolicContext, and sometimes BDDVariableSet. What does "context" mean in this... context?
2. Some of the functions have an AsynchronousGraph object called stg; is this actually a state transition graph of some kind, or just an object with methods for computing state transitions? If it's the latter, then what is the difference between an AsynchronousGraph an a BooleanNetwork in AEON?

[daemontus]

1. Ah, well... in this case, context indeed means different things :/ In general, my rationale was "context provides information that I need to fully interpret some of the other arguments", but this is of course a very loose definition. Typically:
   • BddVariableSet tells me how to interpret the variables in a "generic" Bdd object (i.e. their names and ordering) and allows me to create new, compatible BDDs.
   • SymbolicContext tells me how the objects in a Boolean network (that is, variables and parameters; although we don't deal with parameters in balm that much) map to symbolic BDD variables.
   • AsynchronousGraph isn't really a "context" object, but it by definition contains all the information of a SymbolicContext and a BddVariableSet, hence I wanted to make it available as an argument that would be automatically cast to the correct inner value.

Essentially, an alternative design would turn this into a class hierarchy, in which case Python would be able to cast between these types automatically in most cases (i.e. SymbolicContext inherits from BddVariableSet and AsynchronousGraph inherits from SymbolicContext). But this also (philosophically) doesn't seem "quite right" to me.

I think I should be able to refactor some of these to make them more readable/obvious.

2. AsynchronousGraph is indeed an object for computing state transitions. The key difference is that AsynchronousGraph uses the symbolic BDD encoding while BooleanNetwork is only based on expressions. So a network is typically understood as a "syntactic" description of the Boolean functions, while an stg is a symbolic generator of the transition graph. In retrospect, having a better distinction between "a network based on expressions", "a network based on BDDs", and "a state space generator" would have indeed make more sense.

[jcrozum]

Thanks, I think I get it (mostly anyway). No need to refactor; I'll get to it as I go through the docs. If I run into any additional questions while I'm at it, I'll ping you.