Sphinx extension for BibTeX style citations.
Project description
Overview
The bibtex extension allows BibTeX citations to be inserted into documentation generated by Sphinx, via a bibliography directive, along with :cite:p: and :cite:t: roles. These work similarly to LaTeX’s thebibliography environment and the \citet and \citep commands.
For formatting, the extension relies on pybtex written by Andrey Golovizin. The extension is inspired by Matthew Brett’s bibstuff.sphinxext.bibref and Weston Nielson’s sphinx-natbib.
Installation
Install the module with pip install sphinxcontrib-bibtex, or from source using pip install -e .. Then add:
extensions = ['sphinxcontrib.bibtex']
bibtex_bibfiles = ['refs.bib']to your project’s Sphinx configuration file conf.py.
Installation with python setup.py install is discouraged due to potential issues with the sphinxcontrib namespace.
Minimal Example
In your project’s documentation, you can use :cite:t: for textual citation references, :cite:p: for parenthetical citation references, and .. bibliography:: for inserting the bibliography. For example:
See :cite:t:`1987:nelson` for an introduction to non-standard analysis.
Non-standard analysis is fun :cite:p:`1987:nelson`.
.. 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 Nelson [Nel87a] for an introduction to non-standard analysis. Non-standard analysis is fun [Nel87a].
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:
See :footcite:t:`1987:nelson` for an introduction to non-standard analysis.
Non-standard analysis is fun\ :footcite:p:`1987:nelson`.
.. footbibliography::which will get rendered as:
See Nelson[1] for an introduction to non-standard analysis. Non-standard analysis is fun[1].
Note the use of the backslash escaped space to suppress the space that would otherwise precede the footnote.
Typically, you have a single footbibliography directive at the bottom of each document that has footnote 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.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file sphinxcontrib-bibtex-2.5.0.tar.gz.
File metadata
- Download URL: sphinxcontrib-bibtex-2.5.0.tar.gz
- Upload date:
- Size: 113.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.10.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 71b42e5db0e2e284f243875326bf9936aa9a763282277d75048826fef5b00eaa |
|
| MD5 | a63043ab75321f5b34c695fee867aab3 |
|
| BLAKE2b-256 | eb5494fbcd5eb0532eaa91580d09795c4b6c562b72d5638c2ed5b5cc31d2b1f8 |
File details
Details for the file sphinxcontrib_bibtex-2.5.0-py3-none-any.whl.
File metadata
- Download URL: sphinxcontrib_bibtex-2.5.0-py3-none-any.whl
- Upload date:
- Size: 39.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.10.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 748f726eaca6efff7731012103417ef130ecdcc09501b4d0c54283bf5f059f76 |
|
| MD5 | cafffa1502fe1d3294064e0536d1d5bf |
|
| BLAKE2b-256 | b2173be04de2ed752996654895558db01a30d64759b2c7120e7692402b8d4e19 |
