# Getting Started

## Overview

# pybtex-docutils

A docutils backend for pybtex.

## Overview

The pybtex docutils backend allows BibTeX citations to be inserted into documentation generated by docutils.

- Download: https://pypi.org/project/pybtex-docutils/#files

- Documentation: https://pybtex-docutils.readthedocs.io/en/latest/

- Development: http://github.com/mcmtroffaes/pybtex-docutils/

## Installation

For use with Sphinx, simply install sphinxcontrib-bibtex.

For use with pure docutils, install the module with `pip install pybtex_docutils`, or from source using `pip install -e .`.

## Minimal Example

For use with Sphinx, refer to the sphinxcontrib-bibtex documentation.

For use with pure docutils, the module exposes a new `simplebibliography` directive, which will generate a citation for every entry in the specified bib files. This new directive is only intended for simple single document workflows that do not require the full power of Sphinx. You need exactly one of these directives in your document, placed at the location where you want the citations to appear (typically, at the end).

For example:

    See  [Nelson1987]_ for an introduction to non-standard analysis.

    .. simplebibliography:: refs.bib

where `refs.bib` might contain:

    @Book{Nelson1987,
      author = {Edward Nelson},
      title = {Radically Elementary Probability Theory},
      publisher = {Princeton University Press},
      year = {1987}
    }

Note that citation keys are used as labels. For this to work, it is thus necessary that all keys in your bib file are valid citation labels for docutils. In particular, they cannot contain colons. This limitation is lifted in `sphinxcontrib-bibtex`, which also provides many more citation features.

To use the directive, you have to write your own command script (there seems to be no other way currently to extend docutils). For instance:

    #!/usr/bin/env python3
    from docutils.parsers.rst import directives, Directive
    from docutils.core import publish_cmdline, default_description

    from pybtex_docutils import SimpleBibliography

    description = ('Like rst2html5.py, but with .. simplebibliography support'
                   + default_description)

    if __name__ == '__main__':
        directives.register_directive("simplebibliography", SimpleBibliography)
        publish_cmdline(writer_name='html5', description=description)

You can then run this command as if you would run `rst2html5`.

## Installation

Install the module with `pip install pybtex-docutils`, or from source using `python setup.py install`.

## Minimal Example

    import io
    import pybtex.database.input.bibtex
    import pybtex.plugin

    style = pybtex.plugin.find_plugin('pybtex.style.formatting', 'plain')()
    backend = pybtex.plugin.find_plugin('pybtex.backends', 'docutils')()
    parser = pybtex.database.input.bibtex.Parser()
    data = parser.parse_stream(io.StringIO(u"""
    @Book{1985:lindley,
      author =    {D. Lindley},
      title =     {Making Decisions},
      publisher = {Wiley},
      year =      {1985},
      edition =   {2nd},
    }
    """))
    for entry in style.format_entries(data.entries.values()):
        print(backend.paragraph(entry))

would produce:

    <paragraph>
      D. Lindley. <emphasis>Making Decisions</emphasis>.
      Wiley, 2nd edition, 1985.
    </paragraph>