First pass on documentation

[gvegayon]

Goal

Give a first pass on the documentation, ensuring all the basics are there.

Context

Agreed by the team, we want to have good documentation from the beginning of the project.

Required features

1. Each python function under model/src/pyrenew should:

• Have a docstring featuring (i) a description, (2) parameters, and (3) outputs following numpy's style.

• All functions should have type hints (link)

  For the latter, here is an example of a good typed hinted function:

  import jax.numpy as jnp
  from pyrenew.metaclass import RandomVariable
  
  def myfun(
    x: str,
    y: jnp.array,
    z: RandomVariable
    ) -> None

2. In the case of the demos under model/docs, these should also be checked.

3. __init__.py files should have a description of the module/submodule (currently missing).

Specifications

The following files under model/src/pyrenew should be checked:

@AFg6K7h4fhy2:

• Top-level directory.
• latent/
• model/
• observation/

@cshelley

• process
• Quarto files under model/docs.

Create a single PR per checkbox. PRs should use #16 as a baseline (so either wait until it is merged or use it as a baseline when creating the branch).

[gvegayon]

@cshelley, I would start 1 PR for checking the stuff under docs, but first, wait for #39 to be merged, as I've added lots of docs there. @AFg6K7h4fhy2, let's meet with @cshelley to see how we distribute this.

[AFg6K7h4fhy2]

@cshelley Just flagging you here to indicate that all PRs blocking some of the documentation modification are now no longer blockers.

[AFg6K7h4fhy2]

I am far along with this and suspect this didn't immediately come to mind given my anchoring off of some of the existing docstrings, but I think we can replace something like

https://github.com/CDCgov/multisignal-epi-inference/blob/585a90298e69e713c7a207a0d913b469dfefc766/model/src/pyrenew/model/rtinfectionsrenewal.py#L248

with this:

observed_infections: Optional[ArrayLike] = None,

(where Optional comes from typing), if the docstring body is to look like:

https://github.com/CDCgov/multisignal-epi-inference/blob/585a90298e69e713c7a207a0d913b469dfefc766/model/src/pyrenew/model/rtinfectionsrenewal.py#L257-L258

[AFg6K7h4fhy2]

Current situation is that I need to make 2 other PRs for the deterministic folder (not originally assigned, but I can cover it) and the top-level files. After getting those submitted, I intend to review and address comments across the old PRs—76, 74, and 73—along with new ones. Once this issue is complete, I can address #38

[AFg6K7h4fhy2]

Across some of the PRs, I will change my type-hinting behavior and default to the built-in generic types (e.g., list[str]), which became supported in Python 3.9+, instead of using the type-hints from typing that I had gotten used to since Python 3.5+ (e.g., from typing import Dict, List, Tuple) since this is the direction Python seems to be heading for the future. Nonetheless, typing is still needed for something like Callable to be imported. This behavioral-change also includes using Python 3.10's | instead of Union.