add missing objects and modules to docs

[OriolAbril]

• important background, or details about the implementation
  • I have added what I believe is everything to the api docs. However, a thorough review is still
    needed. Not only I have guessed what should be documented, what is public and what isn't
    but I have also generally preserved file groupings but there might be better conceptual
    groupings we could use
  • I have documented everything where I believe we want users to import the objects from.
    This means that most objects are documented at pymc.<object> and that therefore,
    as this is what we use in code, will make codeautolink work in pymc-examples, notebooks
    will automatically generate links to the right api docs within the code itself.
• are the changes—especially new features—covered by tests and docstrings? NO, 99.9% of
  the docstrings need to be fixed to follow numpydoc, I won't fix any docstring in this PR,
  we'll tackle docstrings in the sprint.
• linting/style checks have been run

[codecov]

Codecov Report

Merging #5439 (e70d038) into main (4fedb60) will decrease coverage by 0.01%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##             main    #5439      +/-   ##
==========================================
- Coverage   81.41%   81.39%   -0.02%     
==========================================
  Files          82       82              
  Lines       14213    14215       +2     
==========================================
- Hits        11572    11571       -1     
- Misses       2641     2644       +3     

Impacted Files	Coverage Δ
pymc/distributions/__init__.py	100.00% <ø> (ø)
pymc/distributions/distribution.py	91.40% <ø> (ø)
pymc/ode/__init__.py	100.00% <ø> (ø)
pymc/__init__.py	100.00% <100.00%> (ø)
pymc/backends/__init__.py	100.00% <100.00%> (ø)
pymc/math.py	70.04% <100.00%> (+0.14%)	⬆️
pymc/parallel_sampling.py	86.71% <0.00%> (-1.00%)	⬇️

[canyon289]

Agree with the numpydoc standard. Its really hard to follow this library internally when docstrings are missing or not implemented. Its doubly hard when I have to search manually using an API.

+100 to standardizd docstrings so we can easily compile with sphinx/napoleon

[OriolAbril]

Agree with everything you said, but this PR is not modifying docstrings nor doing anything related to numpydoc. I am only making sure all functions appear in the api section of the website.

What we have currently: https://docs.pymc.io/en/latest/api.html

What we'll have after merging this PR: https://pymc--5439.org.readthedocs.build/en/5439/api.html

If the docstring is empty the page of that object will exist but be empty, if the docstring is badly formatted then the parameter types might not be rendered as links... we still need to fix all the docstrings (which is one of the main contributions we aim for at the sprint, see https://pymc-data-umbrella.xyz/en/latest/sprint/docstring_tutorial.html). This PR doesn't fix any docstring nor it will fix any docstring.

[OriolAbril]

@Sayam753 tried the auto documenting for math but can't really manage sphinx to not ignore the __all__. Not sure it is worth it, I think all methods are documented now, if we use the manual way we can also group functions in linalg, logic... so they are easier to find with each group having its own title,. It can also be a plus

[twiecki]

Is there a scripted way we can check that everything is included? maybe add it to pre-commit?

[OriolAbril]

Is there a scripted way we can check that everything is included? maybe add it to pre-commit?

not that I know of, especially given the complexity of pymc and submodules. I have no confidence in having gotten the public api right, especially for objects that are not imported at the top level namespace. Take shape utils for example: https://docs.pymc.io/en/latest/api/shape_utils.html. They are available as pymc.distribution.shape_utils.<object> and are not imported at the top level. If they hadn't already been present I would definitely have excluded them from the docs. Are there other submodules like that? I am quite sure the answer is yes. there need to be more public things in tuning for example but I don't know how many nor how they are exposed.

sphinx build an index called objects.inv which is what intersphinx uses to convert :class:`pymc.Normal` to a link pointing to its docs. If we had a way of programatically identifying the public api then we could check everything has an entry there, not as a pre-commit check but after building the docs.