Skip to content

UsingBibTeXCitationsInSphinx.rst

Latest commit

 

History

History
185 lines (122 loc) · 5.35 KB

UsingBibTeXCitationsInSphinx.rst

File metadata and controls

185 lines (122 loc) · 5.35 KB
tocdepth:2

Managing bibliographic citations in Sphinx

Introduction

reStructuredText :ref:`rst-citations-ref` are ill-adapted to parenthetical referencing (a.k.a. the `Harvard System of Referencing`_).

An alternative is to (manually) use the `authorship trigraph`_ (common in older computer science texts).

The citation begins with 4 letters:

  • one author: first 4 letters of name
  • two authors: first 2 letters of author1, first 2 letters of author2
  • three authors: first 2 letters of author1, first letter of author2, first letter of author3
  • four authors: first letter of each author
  • more than four authors: first letter of first four authors

The first letter of a name is always upper case.

After the authors' initials, put the two digits of the year (century-disambiguation is ignored).

If the symbol is exactly the same for two references, a lower case letter is attached.

To facilitate editing, citation text should be kept at the bottom of the document after a "References" rubric heading, like this:

.. rubric:: References

.. [BiDB79] Biskup, J.; Dayal, U.; Bernstein, P.A..: Synthesizing independent database schemas. In: ACM SIGMOD 1979 Int. Conf. On Management of Data Proceedings, S. 143-151.

.. [BeBe79a] Beeri, C.; Bernstein, P.A.: Computational problems related to the design of normal relational schemas. ACM Trans. Database Syst., No. 1, 1979, S. 30-59.

.. [BeBe79b] Beeri, C.; Bernstein, P.A.: Computers are stupid. ACM Trans. Database Syst., No. 4, 1979, S. 253-266.

A similar option is to use the BibTeX alpha style:

  • one author: first 3 letters of the last name
  • two to four authors: first letters of last names concatenated
  • more than four authors: first letters of last names of first three authors concatenated and a "+" sign at the end.

For the examples above, the alpha style citation would be: [BDB79], [BB79a] and [BB79b], respectively.

Using Sphinx BibTeX extension

Parenthetical referencing can be produced in Sphinx_ using the sphinxcontrib-bibtex_ extension.

The sphinxcontrib-bibtex_ extension allows BibTeX_ citations to be inserted into documentation generated by Sphinx.

The extension defines a new bibliography directive and a new cite role.

These work similarly to the LaTeX's thebibliography environment and \cite command.

The references are stored in a separate plain text BibTeX format file. Currently, only the unsrt and plain BibTeX styles are supported.

Installing the extension

The module is installed with:

pip install sphinxcontrib-bibtex

This is a tip.

For Windows users. To facilitate the installation of 3rd party Python packages, follow the instructions on how to `add Distribute and Pip to the Python installation`_.

Including the extension in the project configuration file

The Sphinx project conf.py file must be altered to include:

extensions = ['sphinxcontrib.bibtex']

Example

In the document, use the following syntax:

See :cite:`Strunk1979` for an introduction to stylish blah, blah...

And place the directive at the end of the document:

.. bibliography:: references.bib

The references.bib file should contain a BibTex_ bibliography, including an entry for:

@BOOK{Strunk1979,
  title = {The Elements of Style},
  publisher = {Macmillan},
  year = {1979},
  author = {Strunk, Jr., William and E. B. White},
  edition = {Third}
}

Using the Sphinx Natbib Extension

A more flexible alternative is to use http://wnielson.bitbucket.org/projects/sphinx-natbib/

This documentation can be completed iff required in this specific project.

Using the Sphinx Thesis Resource

See also http://jterrace.github.io/sphinxtr/html/ch-intro/index.html for various useful adaptations/extensions of Sphinx.

Using LaTeX directly in Sphinx

For advanced users, LaTeX can also be used directly in Sphinx (when only LaTeX output is required):

See :raw-tex:`\cite{Strunk1979}` for an introduction to stylish blah, blah...

And insert the bibliography at the end of the document:

.. raw:: latex

 \bibliographystyle{plain}
 \bibliography{listb.bib}

Managing BibTeX bibliographies

The BibTeX files can be easily managed with JabRef_.

JabRef is an open source bibliography reference manager. The native file format used by JabRef is BibTeX, the standard LaTeX bibliography format.

JabRef runs on the Java (version 1.6 or newer), and should work equally well on Windows, Linux and Mac OS X.