Documentation system using mkdocs

[twiecki]

Addresses #346.

What's nice about mkdocs, compared to sphinx, is that the source is markdown rather then rest. That means documentation can be written as IPython NBs and then automatically integrated.

However, this system publishes to gh-pages which is where currently the pymc 2 docs reside. Not sure if we should move those somewhere else?

[fonnesbeck]

We can now publish this to gh-pages.

[cdeil]

I'm looking at: http://pymc-devs.github.io/pymc3/

There's no API reference docs, right?
Is there a plan to generate those?

Would be great to have and everyone uses Sphinx for that, no?

[fonnesbeck]

This should probably be a criterion for moving from beta to release.

I'm not as sold on Sphinx as I once was. I would personally prefer a markdown-based system rather than restructured text.

[twiecki]

mkdocs/mkdocs#641

[cdeil]

I'm not a huge Sphinx fan, specifically it's very complex, the build is slow and the error messages cryptic.
I have no idea if mkdocs is better on those accounts or what made you choose it, but can it do these things, which are pretty important for docs for a project with many classes?

• cross-link high-level and API docs
• good search
• link to code for each class / function / method?

Make a new PyMC3 issue with the feature request for API docs because this one is closed?

[PaulSorenson]

Although I haven't tried it I thought you could mix .md files with .rst in your docs (sphinx-doc/sphinx#1747). The autodoc feature of sphinx among others are handy.

[twiecki]

Personally, I never look at the compiled manual but rather use help() but I can see that others might find it useful. Moreover, some of the docstrings use latex which should be compiled. I bet we can just borrow that from pymc2. @cdeil Definitely open up a new issue on this.

The way to go is probably have mkdocs for the docs and sphinx autodoc for the manual.

[d0ugal]

The nice thing about separating them is that you can clearly show the split between prose and auto-generated docs. The downside is that it is hard to make them feel well integrated, but given the prose markdown will reference the rst and never the other way around it wouldn't be that bad either.