cask/cask — pull request #215 by lunaryorn (2014-05-25 12:26:17+00:00)
Title: Re-write documentation with Sphinx

I have rewritten the documentation in Sphinx. A preview is available at http://cask.readthedocs.org/en/sphinx-docs/.

# Advantages

## Markup, processing and output

- Based on [Sphinx](http://sphinx-doc.org/), a rock-solid, battle-tested documentation tool
- Markup support for cross-referencing (e.g. no need to manually assign and reference HTML anchors)
- Automatic table of contents, both [globally](http://cask.readthedocs.org/en/sphinx-docs/index.html#user-guide) and [locally](http://cask.readthedocs.org/en/sphinx-docs/dev/api.html#cask-api)
- Automatic [index generation](http://cask.readthedocs.org/en/sphinx-docs/genindex.html)
- Automatic [docstring extraction](http://cask.readthedocs.org/en/sphinx-docs/dev/api.html#el.function.cask-add-dependency), with [sphinxcontrib-emacs](http://sphinxcontrib-emacs.readthedocs.org/)
- Many different output formats, so we could build an Info manual or a manpage for Cask in future.

## Development

Docs are in the main repo now, which makes updates to the documentation easier, and let's us enforce requirements such as “pull request must be accompanied by appropriate documentation”.

## Building and publishing

- Automatically built on ReadTheDocs, after every commit on `master`.
- Tags can be build separately, and are published under dedicated URLs, so we get versioned documentation, i.e. on for Cask 0.7, another for Cask 8.0, and so forth.
- We get a nice and responsive HTML theme for free, including a documentation-wide search.

# Disadvantages

- Dependency on Python, Sphinx and sphinxcontrib-emacs to build the documentation, which makes setup a little complicated. I tried to [document the process of building](http://cask.readthedocs.org/en/sphinx-docs/dev/contributing.html#documentation) the docs, though.
- Need to learn reStructuredText plus the extra markup from Sphinx and sphinxcontrib-emacs. It's not a lot, and the concepts are really easy to understand, but still…
- Well, reStructuredText itself might be a disadvantage, since it's less popular than Markdown, which might put contributors off. Still, larger projects than ours are using Sphinx as well, e.g. [LLVM](http://llvm.org/docs/).

# TODO

- [ ] Add @rejeep as maintainer on readthedocs. You'll need an account on that service
- [ ] Rewrite the introduction?