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

Closed
latk opened this Issue Mar 5, 2018 · 3 comments

Comments

Projects
None yet
2 participants
@latk
Member

latk commented Mar 5, 2018

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

This comment has been minimized.

Contributor

chrta commented Apr 6, 2018

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

This comment has been minimized.

Member

latk commented Apr 6, 2018

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

@chrta

This comment has been minimized.

Contributor

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