We migrated a while ago all our python docs from sphinx and the free readthedocs to mkdocs. Two main reasons:
- we like markdown more and starting (actually we converted to markdown with pandoc) with a bunch of markdown files was a breeze. We also did not lost advanced documentation features because there are plenty of fantastic mkdocs plugins.
- readthedocs was unreliable for us but we also did not wanted to pay for our open source software documentation generation + hosting.
At the end we have an auto generated mkdocs with GitHub+Travis and all searchable with the fantastic mkdocs static page search functionality (maybe the biggest feature of mkdocs)
I really dislike .rst (and .md in Sphinx is less than great) so I'd love to switch from Sphinx. Do you know if there's mkdocs has an equivalent to Sphinx's autodoc?
You would loose online search capabilities with this approach or we had to implement it ourself which would be a waste of time because we wanted to write docs not the system behind the docs. We also faced problems with the styling on Sphinx over time (the ready to use styling templates on mkdocs only needed very little modifications from our side).
Yes I know. It was not reliable enough for us and sometimes it failed generating the docs. Paying for it (don't know if this would improve the situation) was out of question for us.
Yep, just search for DNS CNAME handling on GitHub docs. We put also Cloudflare DNS in front of it to get TLS/SSL but I've heard this is not necessary anymore nowadays.
you're right it doesn't cost money however GitHub pages only just started handling SSL certificates for custom domains recently (https://blog.github.com/2018-05-01-github-pages-custom-domai...). before that you had to use a provider like cloudflare to handle the termination.
- we like markdown more and starting (actually we converted to markdown with pandoc) with a bunch of markdown files was a breeze. We also did not lost advanced documentation features because there are plenty of fantastic mkdocs plugins.
- readthedocs was unreliable for us but we also did not wanted to pay for our open source software documentation generation + hosting.
At the end we have an auto generated mkdocs with GitHub+Travis and all searchable with the fantastic mkdocs static page search functionality (maybe the biggest feature of mkdocs)
End result: https://docs.pybossa.com (hosted on GitHub)
Source: https://github.com/scifabric/docs.pybossa.com