:tocdepth: 2

.. role:: raw-tex(raw)
    :format: latex html

.. highlight:: rst

.. metadata-placeholder

   :DC.Title:
   	Managing bibliographic citations in Sphinx
   :DC.Creator:
   	Nery, Fernanda
   :DC.Date:
   	2013-05-25
   :DC.Description:
      Overview on the available alternatives for bibliographic citations  in Sphinx.
   :DC.Language:
   	en
   :DC.Format:
   	text/x-rst
   :DC.license:
      http://creativecommons.org/licenses/by-sa/4.0/
   :DC.Rights:
      Public
   :DC.RightsHolder:
      Fernanda Nery 2013 © CC BY-SA 4.0 http://creativecommons.org/licenses/by-sa/4.0/

.. _rst-biblio-ref:

Bibliographic citations
##########################################

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
   

Including the extension in the project configuration file
=========================================================

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

.. code-block:: python

   extensions = ['sphinxcontrib.bibtex']
   bibtex_bibfiles = ['bibliographyReferences.bib']
   # The default bibliography style is 'alpha'
   # Other options are 'unsrt' (i.e. unsorted, references appear in the order they are cited in the document).
   bibtex_default_style = 'unsrt'

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:

.. code-block:: latex

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

.. topic:: 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.

.. topic:: Using the Sphinx Thesis Resource

   See also the `Sphinx Thesis Resource`_
   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_ or with Zotero_.

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

Both JabRef and Zotero are available on Windows, Linux and Mac.


.. links-placeholder

.. include:: ../_sharedFiles/Links.rst