MkDocs 1.0
mkdocs.org
mkdocs.org
- 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)
Actually, rtd is free for OSS projects
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.
Cheers to 1.0!
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.
* MkDocs seems to have more themes that are actively developed. My favorite is mkdocs-material (https://github.com/squidfunk/mkdocs-material), example can be seen here: https://squidfunk.github.io/mkdocs-material/.
* Most of the features of Sphinx can be used natively or with some plugins for MkDocs. (https://github.com/brianjking/1upkeyboard-docs/blob/master/m...)
* Easy to implement MkDocs with Travis-CI or other CI systems to test/build/deploy documentation on GitHub pages, Gitlab pages, etc. (https://github.com/brianjking/1upkeyboard-docs/blob/master/....)
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.
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.
But I had to switch off the search functionality because it was causing a slowdown when displaying the page (you couldn't even scroll?).
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.
Edit: Some answers in the issue tracker: https://github.com/mkdocs/mkdocs/issues?utf8=%E2%9C%93&q=is%...
Does it split evenly to anyone who wrote code? What about people who only review and merge PRs?
What about if someone was unavailable for a month or two—do they still get a cut for current donations?
I help maintain marked.js.org and we currently don’t accept donations because of these questions.
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.