Writing references

If you want to add references to your documentation, you can use the sphinxcontrib-bibtex extension.

Please refer to the sphinxcontrib-bibtex documentation for full details. However, some notes and tips are provided below for compatibility with the mdanalysis-sphinx-theme.

Basic use

Setting up the reference file

Generally references should be provided as a BibTeX .bib file. In MDAnalysis, this is traditionally called references.bib and is placed in the same directory as the conf.py. For an example, see the MDAnalysis reference file.

The extension and the references.bib file should then added to the conf.py file as below:

extensions = [
    'sphinxcontrib.bibtex',
]

bibtex_bibfiles = ['references.bib']

Citing references in text

References can be cited in text using :cite: or :footcite:. Which one to use depends on if you want to display a “local” or a “global” bibliography. A global bibliography is a single reference list that is rendered on its own page, with the following directive:

.. bibliography::

A bibliography directive picks up all references cited using the :cite: directive across all the documentation.

A local bibliography is one that is rendered on a particular page with other documentation. This is done using the :footcite: and with the following directive:

.. footbibliography::

A footbibliography directive only displays the references cited on that particular page for display.

Important

If you are trying to render a .. bibliography:: on a page with other documentation, it must be the last item on the page. Otherwise, it will displace any other content that follows. In general, it is safest to use a .. footbibliography:: if there is any other content on the page. Please see the mdanalysis-sphinx-theme Issue #25 for more details.