{"id":5016,"library":"pybtex-docutils","title":"pybtex-docutils","description":"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.","status":"active","version":"1.0.3","language":"en","source_language":"en","source_url":"https://github.com/mcmtroffaes/pybtex-docutils","tags":["docutils","pybtex","bibliography","rst","citations","latex"],"install":[{"cmd":"pip install pybtex-docutils","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core bibliography processing engine.","package":"pybtex"},{"reason":"Core documentation utilities for reStructuredText processing.","package":"docutils"}],"imports":[{"note":"Used to register the 'simplebibliography' directive in custom Docutils scripts.","symbol":"SimpleBibliography","correct":"from pybtex_docutils import SimpleBibliography"},{"note":"The primary backend class, also accessible via pybtex.plugin.find_plugin('pybtex.backends', 'docutils').","symbol":"Backend","correct":"from pybtex_docutils import Backend"}],"quickstart":{"code":"import io\nfrom docutils.parsers.rst import directives, Directive\nfrom docutils.core import publish_cmdline, default_description\nfrom pybtex_docutils import SimpleBibliography\n\n# Create a dummy .bib file\nwith open('refs.bib', 'w') as f:\n    f.write('''\n@Book{Nelson1987,\n    author    = {Edward Nelson},\n    title     = {Radically Elementary Probability Theory},\n    publisher = {Princeton University Press},\n    year      = {1987}\n}\n''')\n\n# Create a dummy .rst file\nwith open('example.rst', 'w') as f:\n    f.write('''\n.. highlight:: python\n\nExample Document\n================\n\nSee {Nelson1987}_ for an introduction to non-standard analysis.\n\n.. simplebibliography:: refs.bib\n''')\n\n# Register the directive and publish the document\ndescription = ('Like rst2html5.py, but with .. simplebibliography support' + default_description)\ndirectives.register_directive(\"simplebibliography\", SimpleBibliography)\npublish_cmdline(writer_name='html5', description=description, argv=['example.rst', 'example.html'])\n\nprint(\"Generated example.html with bibliography.\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure BibTeX citation keys do not contain colons, or use `sphinxcontrib-bibtex` for Sphinx projects if more complex keys are needed.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For Sphinx-based projects, install and configure `sphinxcontrib-bibtex` instead of relying on `pybtex-docutils` directly.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}