BPE2: build and publish documentation

[anilbey]

Once BPE2 becomes the master branch the following are needed to build an up-to-date documentation.

• create files to represent sphinx structure for each API page
• have a link to refer to the e-feature documentation https://bluebrain.github.io/eFEL/efeature-documentation.pdf
• complete missing docstrings
• Add a paragraph to the README to describe the general way BPE works.
• [OPTIONAL] use type hints in some function/method signatures to make sure the parameter and return types are always correct and they never go out of date (unlike docstrings). https://pypi.org/project/sphinx-autodoc-typehints/ This feature also shortens the docstrings. Moreover, IDEs and static code analysis tools (like pylint, mypy) read these signatures to prevent misuses.

[DrTaDa]

Thanks for the list !
I will take care of the docstrings.

[anilbey]

Thanks @DrTaDa !

[DrTaDa]

A first batch: #99

[DrTaDa]

For the link to the e-features, I put it in the example notebook for now.
I think you can add to the todo list: Add a paragraph to the README to describe the general way BPE works.

[DrTaDa]

create files to represent sphinx structure for each API page

What does that mean ?

[anilbey]

These rst files under docs/source to tell how the API documentation should be structured.
https://github.com/BlueBrain/BluePyOpt/blob/master/docs/source/ephys.rst

[DrTaDa]

Aren't these files supposed to be created automatically ?

[anilbey]

The html files are generated using these rst files but the rst files are manually created because they can be created in different ways. Using these files we can specify which classes and functions to show in which page it's like the main structure of the documentation. For example all ecodes can be documented in one page or there can be a single page for each one of them.

[DrTaDa]

I give up on sphinx for this week 😄