Rewrite docs using Sphinx

[tysonclugg]

@paltman @blueyed

I'm working on a PR for #523 which necessitates updating the docs. I haven't figuring out how to preview my doc changes, particularly given I need to link between different documents. I feel like I'm missing something.

Given the docs aren't very up to date, and not well publicised, I'm considering updating the docs to use ReStructuredText/Sphinx (which I'm very familiar with) instead of Markdown. I'd perform the conversion using pandoc, and give instructions on how to preview changes whilst editing the doc sources. The resulting docs could be uploaded to the Python Package Index (pythonhosted.org) as a part of the release process.

Would a pull request that changes the docs to use Sphinx/ReStructuredText be welcomed?

[paltman]

We have actually been moving in a direction away from a docs folder and instead putting everything in a comprehensive README in other projects, in Markdown.

For example, see pinax-likes or pinax-referrals.

One could argue that pinax-stripe is a lot bigger application these most Pinax apps and therefore the README would become just too long to have all in one page. I'm not convinced yet that is true but it's a discussion we've had in Slack a few times now.

I would like to keep with a standard authoring language for docs in Pinax, however. That means sticking with Markdown.

Are you opposed to writing in Markdown?

[tysonclugg]

Not opposed, just unskilled. Any suggestions as to how I may preview my doc changes locally, especially browsing between pages using the inter document links?

[blueyed]

@tysonclugg
I like https://github.com/joeyespo/grip in general, not sure how it deals with links though.

[tysonclugg]

@paltman
It's possible to use Markdown with Sphinx, so the goal of having a standard authoring language (Markdown) for docs across all Pinax apps is achievable while using Sphinx.

Sphinx and recommonmark could be added under a dev section in setup.py (extras_require) along with any other dev requirements, so no new dependencies would be introduced for normal installation. This would be a convenient place to add wheel and other dev dependencies that are already in use.

Would a PR that introduces Sphinx (with Markdown; ie: not converting docs to ReStructuredText) for the docs be welcomed?

I see the primary benefit as being able to publish to Read the Docs and/or pythonhosted.org, as well as being able to build (and preview) the docs locally before submitting doc changes in any pull request.

[tysonclugg]

Hmm, I just discovered the thing I've been missing - MkDocs. It's what was used to generate the docs at https://pinax-stripe.readthedocs.io/en/latest/.

Grepping the repo reveals no mention of mkdocs at all, and asking here didn't prompt any memories. Adding documentation on how to run tests and make a release to PyPi + RTD would help prevent further confusion like I've experienced.

I'm happy enough to add either Spinx + recommonmark, or mkdocs to a dev section in extras_require, but the other parts of the release process are something better written by @paltman / @blueyed. Let me know if you'd like any help.