Fix some documentation formatting

[abergeron]

Description

Fix some formatting in the docs to avoid missing sections and weirdly formatted arguments list.

Changes

1. Using custom section is bad because sphinx skips them and doesn't show anything in the rendered docs.
2. Typos in the section names are bad for the same reason.
3. arg : type renders as argtype
arg: type renders as arg: type

Checklist

Tests

• I added corresponding tests for bug fixes and new features. If possible, the tests fail without the changes
• All new and existing tests are passing ($ tox -e py38; replace 38 by your Python version if necessary)

Documentation

• I have updated the relevant documentation related to my changes

Quality

• I have read the CONTRIBUTING doc
• My commits messages follow this format
• My code follows the style guidelines ($ tox -e lint)

Further comments

As a general comment, the docstrings seems to use at least two different markup standards (I have seen numpydoc and reST) often in the same file.

It would be good to standardize on one style and try to enforce it and it may help with odd formatting that may be caused by the doc parser getting confused by the different styles.

[bouthilx]

Thanks for the fixes! There are indeed inconsistencies. Numpy format is the one we favor for this project.