[Enh] Activating numpydoc validation during Sphinx build

[kohlerca]

Currently, the Elephant documentation pages contain formatting errors due to typos or mistakes in the source code in the docstrings. For example, if the colon separating the parameter from the type specification is not separated by a space (e.g., param: type instead of param : type), the expected formatting will not be applied.

Besides the visual impact in the HTML pages, formatting inconsistencies make other approaches to improve the documentation more difficult, such as automatic linking to external documentation pages via intersphinx.

Numpydoc has an option to validate the structure of the docstring against several style requirements, which will throw warnings during the build process that point out inconsistencies.

This PR activates this feature and fixes all the formatting mistakes identified. Issues concerning the Trials classes were ignored as they will be addressed by PR #673. This PR does not address content, only general formatting. Content in the module docstrings is not covered.

The validation checks are split into groups: GL for general structure, SS for the summary string (the first sentence in the docstring), SA for the 'See Also' section, PR for the parameters, and RT for the returns. The checks currently activated are:

• GL01: There must be a line break after the starting quotes """
• GL02: Closing quotes """ must be on the line immediately after the last text.
• GL03: Double blank lines are not allowed in any part of the docstring text.
• GL05: Tabs at the start of a line are not allowed.
• GL06: Unknown section name encountered (e.g., Return instead of Returns).
• GL07: Sections appear in the wrong order.
• SS02: Summary does not start with a capital letter.
• SS03: Summary does not end with a period.
• SS04: Summary contains leading whitespace.
• SA02: See Also description is missing a final period.
• SA03: See Also description must start with a capital letter.
• PR02: Unknown parameters documented.
• PR03: Parameters documented in the wrong order (must follow the function signature).
• PR05: Parameter type must not end with a period.
• PR06: Parameter type uses an incorrect type name (e.g., string instead of str).
• PR07: Parameter description is missing.
• PR08: Parameter description must start with a capital letter.
• PR10: Missing space before the colon separating parameter name and type.
• RT04: Return value description must start with a capital letter.
• RT05: Return value description must end with a period.

Numpydoc validation may throw errors when there exist docstrings in object properties, such as BinnedSpikeTrain.bin_edges. A patch was implemented in conf.py to deal with those cases.

[coveralls]

coverage: 88.592% (+0.1%) from 88.488% — INM-6:feature/docstring_validation into NeuralEnsemble:master

[CozySocksAlways]

LGTM. I only skimmed the doc changes though, as diff was mostly formatting.
There were some warnings in doc build from scipy and sklearn which are unavoidable. Other warnings as mentioned will be fixed in #673.

[CozySocksAlways]

Typo correction