Custom parser for type hints

[araffin]

Type hints are nice to check the code but it makes the documentation hard to read.
We should write a custom parser to display the hints in a cleaner way.

Related: https://michaelgoerz.net/notes/extending-sphinx-napoleon-docstring-sections.html

and https://github.com/agronholm/sphinx-autodoc-typehints

Update after #167: Above added. Remaining TODOs:

• Clean up parentheses in the type hinting (they are formatted as standard text, not in code-style).

Regex used:

(:((param)|(return))\s*[a-zA_z_0-9]*:) (\([a-zA-Z_\[\]\s,\.0-9]+\))

and replace with $1.

[AdamGleave]

Similar issue we should probably fix at the same time: a lot of the docstrings still have types in them, even though the function has type annotations. This causes the types to appear twice in the generated documentation: once in the signature, and once in the parameter description.

[araffin]

This causes the types to appear twice in the generated documentation: once in the signature, and once in the parameter description.

Good point. In fact, at first, I started removing all type hints from the docstrings and using sphinx type hint plugin, but I stopped because it made the doc quite ugly.
Also, because of that, there are inconsistencies between docstrings and type hints... (that's also what I meant by "cleaning the docstrings")