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.
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.
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).
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.
I'm not familiar with asciidoctor, however, I have a fair amount of experience with Sphinx & MkDocs.
POSITIVES OF MkDocs over Sphinx
* Markdown seems to be easier for people to understand and are familiar with as opposed to reStructuredText. However, Sphinx now does allow you to use Markdown as well as reStructuredText.
The times I feel Sphinx is definitely a better choice than MkDocs (from my personal experience):
* If you want to generate PDF & ePUB copies of your files Sphinx seems much more direct, especially if you can use ReadTheDocs (https://readthedocs.org/). Although, there are several MkDocs methods of generating your docs as a PDF using pandoc or other systems. However, depending on what plugins you have in your mkdocs it may cause problems. (https://github.com/search?q=mkdocs+pdf, https://github.com/search?q=mkdocs+pandoc).
* Sphinx seems better for auto documentation for APIs and other code documentation.
They're are quite different beasts all together. I can't think of any reason to use reST and Sphinx under any circumstance other than Python projects. Asciidoctor.js actually has a site generator these days called Antora (aimed at building docs from multiple git repos) it is still far from complete on features compared to Sphinx. MkDocs looks good for small projects although I probably would just use mdBook if there's a need to write in Markdown for some reason.
Also wondering about extensions, how are those handled? Or is this for plain documents only? For example in Sphinx you can mark up figures, youtube videos, graphviz graphs, etc. Are those plugins available with mkdocs?
What about a book with parts? That's one area that Sphinx falls down, and they've been dragging their feet on it so far.
Awesome and congrats. We started using MkDocs for https://aqueduct.io/docs/, 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.
I’ve found that I’m at least more willing to make quick typo fixes and deploy them when I just have to make the change locally and do a single push. This is especially true (for me) when there is some additional web content that is not generated by mkdocs.
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:
Sounds like a theme issue with the online search (we had also problems with search when theme was older or newer than mkdocs), do you experience same behaviour with other themes?
It flattens the text into one big json file and with some JS it searches this flat text file: https://github.com/Scifabric/docs.pybossa.com/blob/gh-pages/... (1.1 MB)
all done automatically on building the site.
There are for sure some limits to this approach because it's all in memory/browser but we only write some software documentation on our side and not really big books.
How the.. I just tried this, and it works, but I don't understand why.
I mean YAML is just another data serialization format and so can be trivially converted anyways, but I thought that YAML had completely different formatting rules than JSON.
> YAML can therefore be viewed as a natural superset of JSON, offering improved human readability and a more complete information model. This is also the case in practice; every JSON file is also a valid YAML file. This makes it easy to migrate from JSON to YAML if/when the additional features are required.
I think that's why I absolutely love YAML: I was able to start using it by writing JSON, then replacing parts of my documents with their "native" equivalents as I got comfortable with it.
- 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