/zot4rst

Primary LanguagePython

zot4rst: Zotero for reStructuredText (docutils)

Background

Zotero is a useful tool for managing citations.

zot4rst is an extension to the Python docutils package for including citations in reStructuredText documents. zot4rst uses a simple citation format, identical to that of pandoc.

zot4rst is developed under Linux, has been tested on Windows, and should run under Mac OS.

Installation

  1. Install Zotero.

  2. Download and install zotxt:

    https://bitbucket.org/egh/zotxt/downloads/zotxt.xpi

  3. Install zot4rst:

    pip install zot4rst

    or you can install from source:

    sudo python setup.py install

Quickstart

See example/example.rst, and the generated example/example.pdf and example/example.html. Citation syntax is identical to pandoc.

zot4rst automatically maps citation keys (e.g., @DoeTitle2010) to entries in the zotero database. The key should be of the form @AuthorTitleDate. So, for the item:

John Doe, “Article,” Journal of Generic Studies, 2006.

You could use: @DoeArticle2006. This should be easy to use, but the reference needs to be unambiguous, which might be a problem if there are multiple items with the same author, title, and year. I am looking into ways to handle this better.

To include Zotero citations in a reStructuredText document, you must use the bundled zrst2* scripts, which have been modified to include support for zotero directives. These executables are installed using setup.py above. Currently, they are:

  • zrst2html
  • zrst2odt
  • zrst2pdf
  • zrst2pseudoxml
  • zrst2rst

Sphinx

To use in sphinx, simply add the zot4rst.sphinx extension to your conf.py file:

extensions = ['zot4rst.sphinx']

Pelican

To use in pelican (version 3.1 or later), add the following to your pelicanconf.py file:

PLUGINS = ['zot4rst.pelican_plugin',]

Details

Some details, in no particular order.

Note that zrst2rst will transform your citations into plain reStructuredText files without the Zotero extension. For example:

A citation group :xcite:`[see @item1 p. 34-35; also @item3 chap. 3]`.

will become:

A citation group (see Doe 2005, p. 34–35; also Doe and Roe 2007,
chap. 3).

and the bibliography will be fully expanded. This can be used to create RST files that will work without zot4rst.

If you use a footnote citation format, zot4rst will insert footnotes for you.

However, if you also use regular autonumbered footnotes in the same section or paragraph, the ordering will be wrong. So if you want to do this, you will need to put your citations in a footnote explicitly. For example:

Water is wet. [#]_ But there are those who dispute it. [#]_

.. [#] :xcite:`[See @item3]`.

.. [#] These people are wrong.