Improve doc

[adrien-berchet]

Fixes #358

The Python API part of the doc was not complete and had several formatting issues. This PR should fix these:

• Remove some warnings during doc generation
• Fix syntax highlighting in doc
• Improve doc for Python API
• Fix an assertion in a test that was always True

[eleftherioszisis]

You have changes that are not reflecting this PR's description. Why did you remove the binding modules separated by context to join them in a single large and hard-to-read file?

[adrien-berchet]

Ah yeah, this is because some methods of mutable classes need to be declared after immutable classes and some methods of immutable classes need to be declared after mutable classes. So all the classes must be defined before the methods. So if we want to keep things separated we need:

• a function that defines and returns mutable classes.
• a function that defines and returns immutable classes.
• a function that takes (almost) all classes as arguments to define the methods of mutable classes.
• a function that takes (almost) all classes as arguments to define the methods of immutable classes.

This was quite cumbersome so I gathered everything at the same place (and in the right order since the order matters). But we could try to split it again.

[adrien-berchet]

Ah and just to explain a bit more: these methods need other classes to be defined before so that Sphinx is able to properly link the argument types or returned types of these methods.

[eleftherioszisis]

I see. but we cannot sacrifice code readability in favor of sphinx, especially for the bindings that are already cumbersome to read and maintain.

[adrien-berchet]

Well, I don't think it's less readable but I am going to try to split it again into several functions.

[eleftherioszisis]

Before doing that, maybe @mgeplf could chip in.

[adrien-berchet]

I split again the functions so it's more readable. It was not so easy because the pybind11::class_ can not be constructed empty, so I had to store these objects into a struct. But in the end should be as readable as before.

[eleftherioszisis]

The documentation build from readthedocs is successful: https://readthedocs.org/projects/morphio/builds/19444990/