Doc fixes

[brandonwillard]

This PR contains numerous Sphinx-related documentation fixes. Only one set of warnings remain after these changes, and fixing those involves a refactor of Type.[Variable|Constant].

[codecov]

Codecov Report

Merging #463 (eeb84b0) into main (eb4f92f) will decrease coverage by 0.00%.
The diff coverage is 88.23%.

❗ Current head eeb84b0 differs from pull request most recent head 0bb28cb. Consider uploading reports for the commit 0bb28cb to get more accurate results

@@            Coverage Diff             @@
##             main     #463      +/-   ##
==========================================
- Coverage   72.52%   72.52%   -0.01%     
==========================================
  Files         174      174              
  Lines       55689    55680       -9     
==========================================
- Hits        40390    40381       -9     
  Misses      15299    15299              

Impacted Files	Coverage Δ
aesara/gpuarray/dnn.py	23.78% <ø> (ø)
aesara/graph/basic.py	91.79% <ø> (ø)
aesara/graph/fg.py	93.22% <ø> (ø)
aesara/graph/op.py	76.90% <ø> (-0.06%)	⬇️
aesara/graph/type.py	84.07% <ø> (ø)
aesara/link/basic.py	89.23% <ø> (ø)
aesara/link/c/interface.py	94.04% <ø> (ø)
aesara/link/jax/dispatch.py	82.05% <ø> (ø)
aesara/scalar/math.py	77.18% <ø> (ø)
aesara/sparse/basic.py	88.96% <ø> (ø)
... and 7 more

[michaelosthege]

Good stuff - looks like a lot of work!

I noticed some inconsistency in the spaces and colons on the type hints in docstrings. The linked resources could help to explain & resolve them.

[brandonwillard]

Good stuff - looks like a lot of work!

I noticed some inconsistency in the spaces and colons on the type hints in docstrings. The linked resources could help to explain & resolve them.

These changes come from an accumulation of doc-related stashes over the past few months. Those empty :s were there to indicate portions of the docstrings that still needed to be filled out; however, now that we've been adding type annotations, I would rather not maintain two copies of the same information, and simply automate the docstring parameters production via the type annotations (e.g. sphinx-autodoc-typehints).

With that in mind, we should focus less on manually meeting the subtleties of NumPy's parameter formatting, since it will ultimately be a wasted effort. Likewise, the entire project doesn't adhere to a single, consistent docstring format, but, once one is formally established, that would entail a pre-commit linter and updates to all the existing docstrings. This can—and should—be done independently.

In the meantime, we need to fix the obvious formatting issues in the rendered documentation, and that's what this PR primarily does.

Formatting has been updated

[michaelosthege]

[...] I would rather not maintain two copies of the same information, and simply automate the docstring parameters production via the type annotations [...]
In the meantime, we need to fix the obvious formatting issues in the rendered documentation, and that's what this PR primarily does.

I agree! Just wanted to make sure that you're aware of the potentially related issue.