Getting Started¶
Including sphinx-git In Your Project¶
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.
Installing sphinx-git¶
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.
Including sphinx-git In Your Sphinx Configuration¶
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']
Add A git Changelog To Your Project¶
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.
Add Details of the Latest Commit to Your Project¶
You can also display information about the state of the repository when the documentation
was compiled with the git_commit_detail
directive:
.. git_commit_detail::
:branch:
:commit: