6 ms·
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
by therealmarv 8y ago
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)
End result: https://docs.pybossa.com https://docs.pybossa.com (hosted on GitHub)
Source: https://github.com/scifabric/docs.pybossa.com https://github.com/scifabric/docs.pybossa.com
- mixmastamyk 8y agoGithub hosts your docs for free, with a custom domain name?
- detaro 8y agoGithub Pages doesn't cost money.
- mixmastamyk 8y agoCustom domain is usually where sites look for revenue ops, though VC/MS money should last for a while.
- burdzwastaken 8y agoyou'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-domains-https/ 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.
- therealmarv 8y agoYep, 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.
- kiliankoe 8y agoIt's not, GitHub automatically registers Let's Encrypt certs for custom domains :)
- mixmastamyk 8y agoCool, thanks. Looking at your yaml, it looks like the title of each doc has to be configured separately? Is that required?
- therealmarv 8y agoNo this is optional. You can also just throw a bunch of .md files in a directory structure and run mkdocs over it to generate a tree for navigation.
- ATsch 8y agoI'm curious why you didn't use the sphinx markdown option and/or use travis and github pages to generate the sphinx docs instead.
- therealmarv 8y agoYou 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).
- stsewd 8y ago> we also did not wanted to pay for our open source software documentation generation + hosting. Actually, rtd is free for OSS projects
- therealmarv 8y agoYes 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.
- wyldfire 8y agoI frequently see failures on RTD doc builds due to memory exhaustion.
- Walkman 8y agoThis is quite nice, high quality documentation, the template is eye-catchy, very nicely structured, well done!
- therealmarv 8y agothx :)
- johnx123-up 8y agoCan someone please compare this to https://github.com/facebook/Docusaurus https://github.com/facebook/Docusaurus and Jekyll? TIA
- drcongo 8y agoI 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?