Install & Compatibility
Where this runs
tested against v1.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.218s · 25.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.210s · 27MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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').
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.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pybtex.database'; 'pybtex' is not a package
This error occurs when the 'pybtex' package, a core dependency for pybtex-docutils, is not installed or incorrectly installed in the Python environment being used.
fixEnsure pybtex is installed in the active Python environment: `pip install pybtex`.
WARNING: could not find bibtex key "MYKEY"
The citation key specified in the reStructuredText document does not correspond to any entry in the provided BibTeX (.bib) files, or there's an issue with splitting bibtex entries across multiple files with repeated keys.
fixVerify that the citation key (e.g., `MYKEY`) exactly matches an entry ID in your `.bib` file(s) and that all required `.bib` files are correctly referenced. Consider consolidating `.bib` files if using multiple.
Citation keys contain colons (e.g., `key:with:colon`) when using with pure Docutils.
When using `pybtex-docutils` directly with Docutils (not through Sphinx and `sphinxcontrib-bibtex`), Docutils' default parsing for citation labels does not support colons in citation keys.
fixRename BibTeX citation keys to remove colons (and any other characters not valid for Docutils citation labels). If colons are necessary, use `sphinxcontrib-bibtex` within Sphinx, which supports them.
AttributeError: 'dict' object has no attribute 'fields'
This error typically arises when a custom Pybtex formatting style attempts to access bibliography entry data using an outdated or incorrect attribute, like `entry.fields['title']`, on an object that is now a dictionary-like structure.
fixUpdate the custom Pybtex style to access bibliography entry data using the current Pybtex API, which often involves direct dictionary-style access, e.g., `entry['title']`.
Upgrade
Version history
1.0.3latest on PyPI · released Aug 22, 2023
Audit
Dependencies
pybtexrequiredCore bibliography processing engine.
docutilsrequiredCore documentation utilities for reStructuredText processing.