Add proper documentation

[costashatz]

We should have a better documentation with automatic API docs and possibly a website?

[costashatz]

I see two options for creating a website:

• https://readthedocs.org/
• https://blog.getpelican.com/

I guess for the API documentation only doxygen is there?

@jbmouret @dalinel @PedroDesRobots can someone start preparing this? I liked limbo's approach and design, but pelican seems to be very easy to use also (I remember that we had many issues with sphinx)..

[jbmouret]

Sphinx + doxygen is not trivial to setup...

What does Pelican? it replaces sphinx?

[costashatz]

What does Pelican? it replaces sphinx?

Yes. I am not super familiar with it, but it was certainly a bit easier to use that what I remember with limbo's website.

Magnum's website is using it and seems to be quite good. Here's a few links:

• m.css
• m.css with Pelican
• Pelican Magnum
• Pelican/m.css with Doxygen
• Pelican/m.css for API docs of python files

I haven't used all these features, but I did manage at some point to create a dummy website with Pelican and m.css in less than 10 minutes time.

I will try to gather more information about this..

[jbmouret]

If we can avoid doxygen + sphinx, I am all for it. I am not sure I will ever be able to make it work again :)

What I wanted with Limbo, however, was to be able to call doxygen results in a text, instead of having these huge doxygen-generated documentation (it's like, doxygen results become a library, it's not independent).

We did things like this:
https://github.com/resibots/limbo/blob/master/docs/api.rst

Where `.. doxygenclass:: limbo::model::MultiGP`` is replaced by the link + documentation of this.

[jbmouret]

Indeed, Magnum + doxygen does not seem bad: https://doc.magnum.graphics/magnum/getting-started.html

[costashatz]

Do not forget to check the super cool and fast search: https://doc.magnum.graphics/magnum/getting-started.html#search