Generate sphinx documentation?

[dmp42]

Follow-up on current discussion around documentation.

[jamtur01]

Can we use a consistent tool with Docker?

[bacongobbler]

I agree with @jamtur01 in a sense. MkDocs/Markdown are great tools, but there are tradeoffs. Markdown has a few less features than ReST (definition lists, sidenotes, footnotes, etc.) due to its nature of being HTML-specific in the sense that processors expect to be generating HTML. From my perspective, I know we've (meaning deis/deis) have wanted to switch over to MkDocs for a while, but ebook and PDF exports built right into Sphinx have been too good of a feature for us to warrant a complete refactor of our documentation, so you might want to look into that and see if you want to make that tradeoff.

On the plus side, Markdown is a great tool for writing documentation. The way headers are generated with Markdown is a little more strict which makes it easier to keep a consistent standard across pages. Markdown's arguably more human-readable than ReST's syntax, and it seems like it's more widely adopted than ReST, which might make for a better contributor's experience.

Just my two cents on the discussion :)