PK {C,I8< < sphinx-git-v8/searchindex.jsSearch.setIndex({objects:{},terms:{explan:4,rtd:[1,4],all:[0,4,2],code:4,just:[0,1],scratch:0,over:4,move:[1,4],rest:3,syntax:4,file:[1,2,3],follow:[0,3],find:2,paramet:4,involv:4,footnot:[4,3],tick:3,nice:4,despis:4,also:2,fix:[1,4],configur:[1,2,3,4],enough:0,topicbranch:4,should:3,add:[1,2,4],daniel:[1,4],voila:2,under:3,els:4,take:4,custom:3,good:3,contribut:[0,1],caus:3,get:[0,1,2,3],python:0,supersed:[1,4],initi:4,mention:[1,4],"new":4,veri:3,now:[1,2,3,4],requir:[0,1,2,3,4],enabl:[1,3],somewher:[2,3],like:0,specif:[1,3,4],changelog:[0,1,2,4],edit:3,anyth:4,list:[4,2],patch:[0,1,4],item:4,exampl:[1,4],updat:[1,4],man:4,each:[4,2],output:[1,2,4],readthedoc:3,where:[2,3],page:[4,3],set:2,bump:4,replac:[1,4],hard:2,excerpt:1,back:2,sanderson:4,see:[0,1,2,4],sampl:4,iter_commit:4,pass:0,our:3,happen:[1,4],best:0,out:[1,3],virtualenv:3,index:[1,4],what:[1,2],guid:[2,3],assum:[2,3],section:[1,2,4],rev:4,content:1,written:0,version:[4,3],welcom:[1,4],between:4,got:0,dashboard:3,solo:0,run:0,navig:3,gener:[2,3],contain:[4,3],extens:[1,2,3,4],host:3,let:4,repositori:[4,3],releas:1,org:3,post:3,becom:4,come:2,box:3,both:[0,4],about:3,pep:0,easi:3,admin:3,could:1,current:4,branch:4,precis:[4,2],credit:4,place:3,isn:3,git_changelog:[1,2,4],pick:[0,1],oddblok:4,commit:[1,3,4],chang:[0,1,2,4],com:3,support:[4,3],first:[4,2,3],pre:4,rang:4,own:0,regardless:4,can:[0,1,2,4],feel:0,onc:[0,2,3],within:1,prefer:4,number:[0,4,2],date:4,alreadi:[0,2,3],done:[1,2],messag:[1,4],ensur:2,sphinx_git:[0,2],txt:[0,2,3],open:[0,1],your:[0,1,2,3,4],unit:0,merg:4,websit:3,differ:2,git:[0,1,2,3,4],from:[1,3,4],pin:3,coupl:4,top:2,two:3,submit:[0,1,3],next:2,avail:[0,3],start:[1,2,3,4],much:0,master:4,includ:[0,1,2,3,4],scope:3,rebuilt:3,tag:4,instal:[0,2,3],more:[0,4],fork:0,head:4,gitignor:[1,4],nvie:3,name:3,watkin:[1,4],checklist:[0,1,4],tool:1,pylint:0,specifi:4,wrestl:4,warn:4,part:[4,2],link:[1,4],accept:4,consult:4,rst:[1,4],don:4,line:[0,4],"true":4,than:[0,1,4],"case":2,pull:[0,4],myself:0,look:2,possibl:4,provid:4,setup:[4,2],outlin:2,displai:4,histori:[1,4],project:[0,1,2,3],defin:4,below:[1,4],paragraph:[1,4],reword:[1,4],abov:3,entri:4,problem:0,toward:2,github:[0,1],gregori:4,control:4,gone:[1,4],would:4,hash:4,conf:2,creat:[1,3],give:[0,4],readi:0,explicit:4,preformat:4,readm:[1,4],argument:4,doesn:0,direct:[1,4],packag:[0,1,3,4],"default":[4,3],intro:[1,4],right:2,have:[0,2,3],pip:[0,2,3],revis:4,work:[0,3],featur:[0,4],check:0,option:4,again:4,surfac:1,gitpython:4,develop:[0,4],form:3,want:[4,2],thing:[0,2,3],rather:[1,4],allow:1,make:[0,4],format:4,when:4,detail:[1,4],eric:4,note:2,how:[0,1,4],need:[0,2,3],wai:[0,2],read:[1,3,4],build:[0,4,2],which:[4,2,3],travi:0,test:0,you:[0,1,2,3,4],document:[0,1,2,3,4],text:4,singl:4,confid:0,even:4,http:3,outsid:3,itch:0,alwai:4,setuptool:4,enter:3,most:[1,4],plai:4,cours:0,stab:0,pdf:[1,4],mai:2,underscor:2,wherev:2,implement:4,recent:[1,2,4],appropri:0,sphinx:[0,1,2,3,4],haven:3,ani:4,doc:[1,2,3,4],caption:[1,4],author:4,request:[0,4],rev_list:4,produc:4,issu:[0,1],inform:0,preced:4,environ:0,probabl:[2,3],thi:[0,1,2,3,4],finalis:[1,4],pars:4,excel:3,togeth:4},objtypes:{},titles:["Contributing","Welcome to sphinx-git’s documentation!","Getting Started","Enabling on Read the Docs","Using sphinx-git"],objnames:{},filenames:["contributing","index","getting-started","read-the-docs","using"]})PK {Cld sphinx-git-v8/search.html
Currently, sphinx-git provides a single extension to Sphinx: the 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:
- Finalise CHANGELOG for v8. by Daniel Watkins at 2013-11-27 03:41:23
- Add Read the Docs documentation to index. by Daniel Watkins at 2013-11-26 11:52:59
- Add documentation on how to configure on Read the Docs. by Daniel Watkins at 2013-11-26 11:51:47
- Reword README intro and add to index.rst. by Daniel Watkins at 2013-11-26 10:28:40
- Replace most of the README with a link to RtD. by Daniel Watkins at 2013-11-26 10:03:25
- Update PR checklist now that examples.rst is gone. by Daniel Watkins at 2013-11-26 09:59:05
- Add Using section, superseding examples.rst. by Daniel Watkins at 2013-11-26 09:57:56
- Mention move to package in CHANGELOG. by Daniel Watkins at 2013-11-26 07:21:00
- Output detailed commit messages as paragraphs rather than captions to fix PDF output. by Daniel Watkins at 2013-11-26 07:06:59
- Update .gitignore. by Daniel Watkins at 2013-11-26 06:58:54
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.
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:
- Finalise CHANGELOG for v8. by Daniel Watkins at 2013-11-27 03:41:23
- Add Read the Docs documentation to index. by Daniel Watkins at 2013-11-26 11:52:59
If you specify more revisions than the history contains, all revisions in the history will be displayed.
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.
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! |
This guide assumes that you already have a Sphinx documentation project configured and building. If that is not the case, see the Sphinx documentation first and then come back.
The first thing you will need to do is install sphinx-git:
pip install sphinx-git
You may also want to include it in your setup.py or requirements.txt to ensure that sphinx-git is installed wherever you generate your documentation; each project will probably have a different way of doing this.
Once you have installed sphinx-git, you need to configure Sphinx to look for it. Find the Sphinx conf.py which is used to generate your documentation. Somewhere in that file (generally towards the top), you will find the extensions setting. Add sphinx_git to this list (note the underscore):
extensions = ['sphinx_git']
All the hard parts are done, now you can add a git changelog to your project! Find a documentation file where you want it and add:
Recent Changes
--------------
.. git_changelog::
Build your documentation and, voila!, you have a git changelog right there in your docs!
There are a number of ways you can configure sphinx-git to output precisely what you want, which are outlined in the next section of the documentation.
Read the Docs is an excellent website that hosts Sphinx-generated documentation (including the documentation for this project, which is probably where you are reading it). This document assumes that you already have your project configured on Read the Docs, using their default configuration [1].
As a custom extension, sphinx-git isn’t supported out-of-the-box by Read the Docs, but it is very easy to get it working!
The first thing you’ll need to do is create a pip requirements file for your documentation. Create a file containing:
sphinx-git
and commit it somewhere in your repository [2] (I will assume it is in requirements/doc.txt for the rest of this document).
Navigate to the Read the Docs admin page for your project. This will be of the form https://readthedocs.org/dashboard/<PROJECT NAME>/edit/. Once on this page, you need to do two things:
Submitting the form should cause your project to be rebuilt, now with sphinx-git available!
Footnotes
[1] | Follow the Read the Docs getting started guide if you haven’t already. |
[2] | You should probably pin that requirement to a specific version, but that is outside the scope of this documentation. This is probably a good place to start reading about it: http://nvie.com/posts/pin-your-packages/ |
sphinx-git is already the work of more than just myself! There are a number of ways that you can contribute to the sphinx-git project.
If there’s a problem with how sphinx-git works, or if there’s a feature that you’d like to see, open up an issue in GitHub. Give as much information as you can and I’ll do my best to get to it!
If you feel confident enough, have a stab at scratching your own itch in sphinx-git. Fork the project on GitHub, make your changes and submit a pull request.
Pull requests will need to pass the Travis CI build; you can run this by doing the following:
$ pip install -r requirements.txt # This installs all of the development requirements
$ travis-solo
This will run the build on both Python 2.6 and Python 2.7. If you’re on an environment that doesn’t have both available then do the best you can, and then open up your pull request; Travis will pick this up and build it for you.
Once you’ve got a patch ready, check the following things:
sphinx-git is an extension to the Sphinx documentation tool that allows you to include excerpts from your git history within your documentation. This could be used for release changelogs, to pick out specific examples of history in documentation, or just to surface what is happening in the project.
See Recent Changes below for an example of what can be done with it.