pybtex-docutils

1.0.3 · active · verified Sun Apr 12

pybtex-docutils is a Docutils backend for the Pybtex bibliography processor. It enables the insertion of BibTeX citations into documentation generated by Docutils, particularly for reStructuredText. The current version is 1.0.3, and while releases are not on a strict schedule, the library is actively maintained.

Warnings

gotcha When using the `simplebibliography` directive directly with Docutils, citation keys in your BibTeX file cannot contain colons. This is because Docutils uses citation keys as labels, and colons are not valid characters for these labels. This limitation is lifted when using `sphinxcontrib-bibtex`.
Fix: Ensure BibTeX citation keys do not contain colons, or use `sphinxcontrib-bibtex` for Sphinx projects if more complex keys are needed.
gotcha The `simplebibliography` directive provided by `pybtex-docutils` is primarily intended for simple single-document Docutils workflows. For projects built with Sphinx, it is strongly recommended to use `sphinxcontrib-bibtex` instead, as it offers more features and better integration with Sphinx's build process.
Fix: For Sphinx-based projects, install and configure `sphinxcontrib-bibtex` instead of relying on `pybtex-docutils` directly.
gotcha Extending Docutils with custom directives like `simplebibliography` currently requires writing a custom Python command script that registers the directive before processing the reStructuredText document. There is no simpler plugin mechanism for pure Docutils outside of a custom script.
Fix: Always prepare a Python script to register `SimpleBibliography` (e.g., `directives.register_directive("simplebibliography", SimpleBibliography)`) and then use `publish_cmdline` or similar Docutils API calls to process your `.rst` files.

Install

pip install pybtex-docutils Install stable version

Imports

SimpleBibliography
```
from pybtex_docutils import SimpleBibliography
```
Used to register the 'simplebibliography' directive in custom Docutils scripts.
Backend
```
from pybtex_docutils import Backend
```
The primary backend class, also accessible via pybtex.plugin.find_plugin('pybtex.backends', 'docutils').

Quickstart

This quickstart demonstrates how to use the `simplebibliography` directive with a pure Docutils workflow. It generates a sample BibTeX file (`refs.bib`) and an reStructuredText file (`example.rst`), then uses a Python script to process `example.rst` into `example.html`, including the bibliography. This setup requires manually registering the `SimpleBibliography` directive with Docutils.

import io
from docutils.parsers.rst import directives, Directive
from docutils.core import publish_cmdline, default_description
from pybtex_docutils import SimpleBibliography

# Create a dummy .bib file
with open('refs.bib', 'w') as f:
    f.write('''
@Book{Nelson1987,
    author    = {Edward Nelson},
    title     = {Radically Elementary Probability Theory},
    publisher = {Princeton University Press},
    year      = {1987}
}
''')

# Create a dummy .rst file
with open('example.rst', 'w') as f:
    f.write('''
.. highlight:: python

Example Document
================

See {Nelson1987}_ for an introduction to non-standard analysis.

.. simplebibliography:: refs.bib
''')

# Register the directive and publish the document
description = ('Like rst2html5.py, but with .. simplebibliography support' + default_description)
directives.register_directive("simplebibliography", SimpleBibliography)
publish_cmdline(writer_name='html5', description=description, argv=['example.rst', 'example.html'])

print("Generated example.html with bibliography.")

view raw JSON →