Using sphinx-git

Currently, sphinx-git provides a single extension to Sphinx: the git_changelog directive.

git_changelog Directive

The git_changelog directive produces a list of commits in the repository in which the documentation build is happening.

By default, it will output the most recent 10 commits. So:

.. git_changelog::

produces:

  • Prepare for version 10 development. by Daniel Watkins at 2015-02-23 10:24:15
  • Finalise CHANGELOG for v9. by Daniel Watkins at 2015-02-23 10:14:56
  • Merge pull request #19 from pomalley/master by Daniel Watkins at 2015-02-23 10:12:50

    Add search_parent_directories=True to Repo creation.

  • Add search_parent_directories=True to Repo creation. by Peter O’Malley at 2015-02-20 09:28:01

    Also, fix test by doing the following: * suppress pylint “Too few public methods” warning * up GitPython version to 0.3.6 Fixes #18 (error with new version of GitPython).

  • Try astroid<1.3 by Daniel Watkins at 2015-02-23 09:46:46
  • Start looking for a version of astroid that supports Python 2.6. by Daniel Watkins at 2015-02-23 09:38:21
  • Pin pylint to a version that supports Python 2.6. by Daniel Watkins at 2015-02-23 09:22:09

    For now.

  • Merge pull request #17 from maurodec/fix_commit_author_unicode by OddBloke at 2014-07-31 15:16:50

    Added support for handling Author name in Unicode.

  • Added support for handling Author name in Unicode. by Mauro de Carvalho at 2014-07-20 09:16:50
  • Fix PEP8 error. by Daniel Watkins at 2014-05-21 04:31:58

As you can see, each revision has the message, author and date output in a list. If a commit has a detailed message (i.e. any part of the commit message that is not on the first line), that will be output below the list item for that commit.

Changing Number of Revisions in Output

If you want to change the number of revisions output by git_changelog, then you can specify the :revisions: argument. So:

.. git_changelog::
    :revisions: 2

produces:

  • Prepare for version 10 development. by Daniel Watkins at 2015-02-23 10:24:15
  • Finalise CHANGELOG for v9. by Daniel Watkins at 2015-02-23 10:14:56

If you specify more revisions than the history contains, all revisions in the history will be displayed.

Specifying Range of Revisions to Output

If you want even more control over the output of git_changelog, then you can specify precisely the revisions you want included using the :rev-list: argument. So:

.. git_changelog::
    :rev-list: v3..v4

produces a list of all the commits between the v3 and v4 tags:

  • Add feature credits to CHANGELOG. by Daniel Watkins at 2013-11-16 17:08:14
  • Add v4 changelog entry. by Daniel Watkins at 2013-11-16 17:06:36
  • Merge pull request #10 from OddBloke/rev_list by OddBloke at 2013-11-16 17:02:41

    Add the possiblity to specify commits using a rev-list parameter.

  • Make a couple of formatting changes. by Daniel Watkins at 2013-11-16 16:59:21
  • add rev-list explanation in README by Gregory Eric Sanderson at 2013-09-30 12:23:39
  • display a changelog using a range of commits by Gregory Eric Sanderson at 2013-09-30 12:06:15

    Adds a new option ‘rev-list’. rev-list lets you define which commit to start from when displaying the changelog. You can use a tag, a branch, a commit hash, an explicit range, or anything else supported by git-rev-parse. Examples: .. git_changelog:: :rev-list: v1.0..HEAD .. git_changelog:: :rev-list: master..topicbranch Consult the man pages of git-rev-parse for more details on the syntax.

  • use a version of gitpython that provides iter_commits() by Gregory Eric Sanderson at 2013-09-30 12:04:34
  • Add CHANGELOG. by Daniel Watkins at 2013-07-07 03:35:43
  • Bump to v4 (for development). by Daniel Watkins at 2013-07-07 03:35:32

and:

.. git_changelog::
    :rev-list: v1

gives you a list of all commits up to the v1 tag (most of which involved me wrestling with setuptools):

  • I despise setuptools. by Daniel Watkins at 2012-07-09 11:46:00
  • Start again. by Daniel Watkins at 2012-07-09 11:39:20
  • Fix requirements. by Daniel Watkins at 2012-07-09 11:37:48
  • Add setup.py. by Daniel Watkins at 2012-07-09 11:34:03
  • Add README. by Daniel Watkins at 2012-07-09 11:33:18
  • Initial implementation. by Daniel Watkins at 2012-07-09 11:16:13

:rev-list: lets you specify revisions using anything that git rev-parse will accept. See the man page for details.

Warning

The :revisions: argument and the :rev-list: argument don’t play nicely together. :rev-list: will always take precedence, and all commits specified by the revision specification be output regardless of the :revisions: argument [1].

Sphinx will output a warning if you specify both.

Preformatted Output for Detailed Messages

If you would prefer for the detailed commit messages to be output as preformatted text (e.g. if you include code samples in your commit messages), then you can specify this preference using the :detailed-message-pre: argument. So:

.. git_changelog::
    :rev-list: 3669419^..3669419
    :detailed-message-pre: True

becomes:

  • display a changelog using a range of commits by Gregory Eric Sanderson at 2013-09-30 12:06:15
    Adds a new option 'rev-list'.
    rev-list lets you define which commit to start from when displaying the
    changelog. You can use a tag, a branch, a commit hash, an explicit
    range, or anything else supported by git-rev-parse. Examples:
    
    .. git_changelog::
        :rev-list: v1.0..HEAD
    
    .. git_changelog::
        :rev-list: master..topicbranch
    
    Consult the man pages of git-rev-parse for more details on the syntax.
    

Footnotes

[1]Patches welcome!