reStructuredText
================

Roles and directives
--------------------

Bibgen provides a reStructuredText_ directive to define a bibliography
database, :rst:dir:`bibliography`, and a directive to cite elements from that
database, :rst:role:`cite`.

A typical document might look like:

.. code-block:: rst

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

.. rst:directive:: 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.

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

   .. code-block:: rst

      .. bibliography::
	 :mendeley:

	 Bayerl2004
	 Gros1998

   In this case, the entries will not be referencable by
   :rst:role:`cite` roles and you will need another
   :rst:dir:`bibliography` directive with no content.
     
.. rst:role:: 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 :rst:dir:`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``
:rst:dir:`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:

.. code-block:: python

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

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

.. _domain: http://sphinx-doc.org/domains.html
.. _reStructuredText: http://docutils.sf.net/rst.html
.. _Sphinx: http://sphinx-doc.org