Improve doc in readthedocs

[acs]

• Select a more attractive theme
• Include info the the landing page (converting markdown to rst)
• Review all the code doc

[acs]

Ok, first step is to select a more attractive theme. Probably this can be done using the readthedocs config options. Let's see.

https://readthedocs.org/projects/rtd-sphinx-theme-sample-project/

• lastest
• nature

To change the theme:

https://docs.readthedocs.io/en/rel/theme.html

89b157c

[acs]

Ok, cool. Now, we need that the README.md is included in land page of readthedocs. And for it, we need to convert it to rst during the doc generation.

[acs]

To include the README.md contents:
https://zj-zhang.github.io/2019/02/24/use_sphinx/

[acs]

There is an issue with m2r now:

sphinx-doc/sphinx#7420

[acs]

When having issues the best reference is: https://docs.readthedocs.io/en/stable/faq.html

[acs]

https://markdown-publishing-guide.readthedocs.io/en/latest/markdown-publishing-guide.html#introduction

[acs]

It is not easy to make Markdown appears right on readthedocs:

https://www.sphinx-doc.org/en/master/usage/markdown.html

Ok, I can convert my markdown pages to rst but the results are just horrible:

So I think I am going to stop trying to include the md files in readthedocs.

It seems that the problem is just with URL links.

[acs]

Ok, so in readthedocs there is also the code documentation to use the library.

[acs]

If we want to have all the doc in readthedocs the approach seems to be to use rst format to create the doc. GitHub supports it.

For example, it is the way used by https://minecraft-stuff.readthedocs.io/en/latest/index.html

[acs]

Taking a look to other projects with nice doc like:

https://bootstrap-datepicker.readthedocs.io/en/master/

they have specific doc in rst format for it.

https://github.com/uxsolutions/bootstrap-datepicker/blob/master/docs/index.rst

Too much effort for the current state of McThings!