New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Manage documentation with Sphinx #235

latk opened this Issue Mar 5, 2018 · 3 comments


None yet
2 participants

latk commented Mar 5, 2018

Sphinx 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 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
  • 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.


This comment has been minimized.


chrta commented Apr 6, 2018

Maybe we could also use in the changelog to link to the related issues. This is a bundled extension (no extra dependency).


This comment has been minimized.


latk commented Apr 6, 2018

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


This comment has been minimized.


chrta commented Apr 6, 2018

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

@latk latk closed this in 51a771f Apr 6, 2018

@latk latk removed the help wanted label Apr 11, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment