Cabal: RFC: migrate documentation to Sphinx, and leverage readthedocs.io for bleeding edge docs

[hvr]

As a proof of concept, I've set up http://cabal.readthedocs.io/ and created a wip/sphinx-doc branch in cabal's repo everyone can push to, to experiment with it.

Everything pushed to that branch should be picked up automatically by cabal.readthedocs.io. I've stolen GHC's stylesheet (/cc @bgamari) to have something working fast. The stylesheet probably up for bikeshedding.

IMO, restructed text is better suited for larger documents than markdown, and we'd be able to use services like cabal.readthedocs.io which provide a few features out of the box (like generating PDF/epub/html, having multiple versions/branches of the documentation etc) -- I'm not saying our primary stable docs ought to be hosted at cabal.readthedocs.io, but it appears like a convenient service for developing and pointing people to bleeding edge / WIP docs.

Do we want to go this route? And if yes, is there someone more experienced with Sphinx who could pick up this task (or at least help/provide guidance)? :-)

/cc @ezyang

PS: quick link to cabal new-build chapter

[23Skidoo]

+1 from me. One immediate improvement that I can think of is that there should be a global TOC, which the "Cabal 1.25 Users Guide" link on top should refer to, and index.rst should be renamed "Introduction"/"Chapter 1". Similarly for the other chapters. This will also give us "Next topic"/"Previous topic" links like the ones in the GHC manual.

[23Skidoo]

@linearray Thanks for working on this, looks really good!

[linearray]

The documentation builds correctly now. Have a looksy and tell me if anything is broken.

How do we integrate the new docs in the release process so that they show up as the official User's Guide at https://www.haskell.org/cabal/users-guide/ ?

[23Skidoo]

How do we integrate the new docs in the release process so that they show up as the official User's Guide at https://www.haskell.org/cabal/users-guide/ ?

That page is updated manually and corresponds to the state of the latest released stable version. But we can add a "nightly" link to the official site that points to cabal.readthedocs.io.

[ezyang]

@linearray Looks good. When you think it's ready, just go ahead and integrate it to mainline (best to migrate earlier rather than later, so we don't end up fixing merge conflicts on docs.)

[hvr]

Tthis was implemented during MuniHac by @linearray via #3780 and got merged. Hence I'm closing this issue now.

http://cabal.readthedocs.org/ always shows the latest master state of the User's Guide (unless it fails to build, then the previous last good snapshot is shown).

[23Skidoo]

Thanks @linearray!