reStructuredText¶

Roles and directives¶

Bibgen provides a reStructuredText directive to define a bibliography database, bibliography, and a directive to cite elements from that database, cite.

A typical document might look like:

.. default-role:: cite

In their classical articles, `Ball1982;Ball1987`
shown that subject performance in a motion discrimination task
is able to increase with training. See also `Matthews1999`.

.. bibliography::
   :mendeley:

.. bibliography::¶

Define a bibliography source for the current document, and print the list of cited items. The optional argument database can be used to specify a non-default database name.

The following options are accepted:

:encoding: name

Defines the encoding of the bibliography database. Defaults to utf-8.

:hidden:

Do not print entries for cited bibliographic elements.

:mendeley:

Indicates to use a Mendeley sqlite database. By default a BibTeX database is assume.

:style: name

Specify the formated citation style. Defaults to harvard1.

:sort: order

Specify order by which bibliographic entries are displayed. Defaults to alpha for alphabetic order. You can use cited for citation order.

bibliography directives can also include content referencing specific bibliographic items to be displayed:

.. bibliography::
   :mendeley:

   Bayerl2004
   Gros1998

In this case, the entries will not be referencable by cite roles and you will need another bibliography directive with no content.

:cite:¶

Insert a formatted citation to a specific bibliography item. The cited item will be added to the printed bibliography. Cited items can be inserted before the corresponding bibliography directive.

Command-line¶

When using the command-line script bibgen, you can specify the bibliography database through as a command-line argument. It will have the same effect as equivalent to using a hidden bibliography directive.

Integration¶

When using bibgen as a library, you can call the bibgen.rst.register() function to register the roles and directives of bibgen.

For instance, in a documentation generated by Sphinx you can add a setup() function which register bibgen to your conf.py file:

def setup(app):
  import bibgen.rst
  bibgen.rst.register()

Alternatively, you could define a domain to cleanly separate the extension.