Docs cleanup
UPDATE for reference see also quantify#10 (closed)
This is a clean up of the docs (but not exhaustive because I have no bandwidth to correct all docstrings).
Mainly fixes this:
To this:
We cannot keep accumulating these warnings! If we do, the docs quality will degrade more and more as no one pays attention to these warnings (most of them are legit and are to be fixed).
An important addition is a dev sphinx extension requirement (scanpydoc.elegant_typehints) that solves a very annoying issue with sphinx_autodoc_typehints.
When doing
from matplotlib.axes import Axeswe actually get
matplotlib.axes._axes.AxesSo there is this mismatch between how the modules are really structured and how the documentation is organized... This will make automatically detected type hints in the docs to not be properly linked to the corresponding docs and throw tons of errors.
The scanpydoc.elegant_typehints solves this and brings some more nice additions like simplifying the display of types in the docs (think of cumbersome to read Union). See the docs themselves built with this.
As a side note, because i get annoyed by this stuff I have accumulated some know-how on properly writing docs/docstrings. I would say it is about time we have some developer docs on how to write docs/docstrings with all the tips that takes 1h for someone to figure out on Google. Would you agree?
Closes #83 (closed)