Update documentation

[gismya]

The documentation is a bit outdated and is due for a refresh.

This will involve:

• a more thorough comparison with differences with the Python API.
• making sure all the information is relevant and correct
• improving the documentation pipeline

[ffMathy]

I would love to help with this. Is there a watch mode for the documentation?

[gismya]

It's now all in the repository as markdown.

[ffMathy]

Awesome!