Manage documentation with Sphinx

[latk]

Sphinx http://www.sphinx-doc.org/ can manage a set of RestructuredText documents. It is widely used to manage the documentation of Python projects.

Currently, our docs are structured like this:

• README.rst serves as an entry point to gcovr, and must render well on GitHub and on PyPI.
• CONTRIBUTING.rst is the development guide, and must render well on GitHub.
• AUTHORS.txt, CHANGELOG.txt and LICENSE.txt are various metadata.
• doc/guide.rst is a more in-depth user guide. It is published on the gcovr home page http://gcovr.com/guide.html. It includes various examples, and the gcovr --help output.

The doc/examples directory includes a few example programs that are included in the documentation. The screenshots are based on these examples.

I want to use Sphinx so that I can (at some later time):

• split the guide into smaller documents
• use some extension for better command line option documentation (fixed-width text is difficult to read)
• use the readme (or something based on it) as the gcovr home page (the current homepage is super minimal, and is maintained by hand)
• host the readme on readthedocs.io
• build and publish new docs automatically through Travis CI.

Would anyone like to take a shot at Sphinx? This shouldn't be too difficult. Note that the *.txt files are not yet translated to ReST, and that the current documentation build process also executes tests and can automatically make screenshots. I would like to preserve this ability under Sphinx.

I'll be happy to assist in any way that I can.

[chrta]

Maybe we could also use http://www.sphinx-doc.org/en/master/ext/extlinks.html in the changelog to link to the related issues. This is a bundled extension (no extra dependency).

[latk]

@chrta That's a very good idea! Would you like to implement this as a separate pull request?

[chrta]

Linking to github issues from the changelog is done in #249. This should only contain the relevant commit after #248 is merged.