We migrated a while ago all our python docs from sphinx and the free readthedocs to mkdocs. Two main reasons:<p>- 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.<p>- readthedocs was unreliable for us but we also did not wanted to pay for our open source software documentation generation + hosting.<p>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)<p>End result: <a href="https://docs.pybossa.com" rel="nofollow">https://docs.pybossa.com</a> (hosted on GitHub)<p>Source: <a href="https://github.com/scifabric/docs.pybossa.com" rel="nofollow">https://github.com/scifabric/docs.pybossa.com</a>
We moved the majority of docs for our projects (<a href="https://github.com/2600hz" rel="nofollow">https://github.com/2600hz</a>) to use mkdocs to build our doc sites (<a href="https://docs.2600hz.com/dev" rel="nofollow">https://docs.2600hz.com/dev</a> <a href="https://docs.2600hz.com/ui" rel="nofollow">https://docs.2600hz.com/ui</a> etc).<p>I have a simple script that receives github webhooks on PR merges to master that fetches the latest version of master and builds the site. So from PR merge to the docs site being updated is now seconds of time.<p>We also integrated building the doc sites into our CI process so PRs will fail if they would cause mkdocs to fail to build the site (borked yaml, make sure docs are included in the yaml, other things).<p>This has been a boon for our community of users and developers. Coupled with our AST parsers that look for code changes that require doc changes, we're getting better about alerting developers of the need to document something, and reviewers of the need if the developer forgot. Not a panacea but has significantly improved doc coverage for Kazoo which has a broad set of APIs available to different types of users.<p>Cheers to 1.0!
If anyone finds it useful, some time ago I made a Docker image of `mkdocs` [1] (with a few extensions, check the dockerfile for details).<p>[1]: <a href="https://hub.docker.com/r/elamperti/docker-mkdocs/" rel="nofollow">https://hub.docker.com/r/elamperti/docker-mkdocs/</a>
Awesome and congrats. We started using MkDocs for <a href="https://aqueduct.io/docs/" rel="nofollow">https://aqueduct.io/docs/</a>, and have since used it for a ton of projects. Some things that we found really useful were that it indexes all of your content for full text search automatically, and it’s stupid simple to deploy it to gh-pages. With a minimal amount of scripting, we push to a mkdocs source branch and it builds and deploys nearly immediately. It has saved us a ton of time and delivered tremendous value.
We love MkDocs! When we originally discovered it we believed it was "good for small projects" but as our product got more complicated we actually never hit any issues. It's amazingly easy to use, extend and customize with great results:<p><a href="https://gravitational.com/teleport/docs" rel="nofollow">https://gravitational.com/teleport/docs</a>
I've just started writing documentation for my project in MkDocs like last week. So far, it's pretty good.<p>But I had to switch off the search functionality because it was causing a slowdown when displaying the page (you couldn't even scroll?).<p>Also I would appreciate if they made changing the theme easier - currently there is only a minified bootstrap css which is a PITA to modify.
What about i18n/multilingual documentation with MkDocs?<p>Edit: Some answers in the issue tracker: <a href="https://github.com/mkdocs/mkdocs/issues?utf8=%E2%9C%93&q=is%3Aissue+i18n" rel="nofollow">https://github.com/mkdocs/mkdocs/issues?utf8=%E2%9C%93&q=is%...</a>
Yet they still have no way for me to buy them a beer.<p><a href="https://github.com/mkdocs/mkdocs/issues/892" rel="nofollow">https://github.com/mkdocs/mkdocs/issues/892</a>