Getting Started¶
Overview¶
Sphinx extensions for BibTeX style citations.
The bibtex extension allows BibTeX
citations to be inserted into documentation generated by
Sphinx, via
a bibliography
directive, and a cite
role, which
work similarly to LaTeX’s thebibliography
environment
and \cite
command.
For formatting, the extension relies on pybtex written by Andrey Golovizin. The extension is inspired by Matthew Brett’s bibstuff.sphinxext.bibref.
Download: https://pypi.org/project/sphinxcontrib-bibtex/#files
Documentation: https://sphinxcontrib-bibtex.readthedocs.io/en/latest/
Development: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/
Installation¶
Install the module with pip install sphinxcontrib-bibtex
, or from
source using python setup.py install
. Then add:
extensions = ['sphinxcontrib.bibtex']
bibtex_bibfiles = ['refs.bib']
to your project’s Sphinx configuration file conf.py
.
Minimal Example¶
In your project’s documentation, you can then write for instance:
See :cite:`1987:nelson` for an introduction to non-standard analysis.
.. bibliography::
where refs.bib
would contain an entry:
@Book{1987:nelson,
author = {Edward Nelson},
title = {Radically Elementary Probability Theory},
publisher = {Princeton University Press},
year = {1987}
}
In the default style, this will get rendered as:
See [Nel87a] for an introduction to non-standard analysis.
- Nel87a
Edward Nelson. Radically Elementary Probability Theory. Princeton University Press, 1987.
Citations in sphinx are resolved globally across all documents.
Typically, you have a single bibliography
directive across
your entire project which collects all citations.
Advanced use cases with multiple bibliography
directives
across your project are also supported, but some care
needs to be taken from your end to avoid duplicate citations.
In contrast, footnotes in sphinx are resolved locally per document. To achieve local bibliographies per document, you can use citations represented by footnotes as follows:
Non-standard analysis is lovely. :footcite:`1987:nelson`
.. footbibliography::
which will get rendered as:
Non-standard analysis is lovely. 1
- 1
Edward Nelson. Radically Elementary Probability Theory. Princeton University Press, 1987.
Typically, you have a single footbibliography
directive
at the bottom of each document that has footcite
citations.
Advanced use cases with multiple footbibliography
directives
per document are also supported. Since everything is local,
there is no concern with duplicate citations when using footnotes.