Overview
--------
The pybtex docutils backend allows `BibTeX <http://www.bibtex.org/>`_
citations to be inserted into documentation generated by
`docutils <https://docutils.sourceforge.io/>`_.
* Download: https://pypi.org/project/pybtex-docutils/#files
* Documentation: https://pybtex-docutils.readthedocs.io/en/latest/
* Development: http://github.com/mcmtroffaes/pybtex-docutils/
.. |imagegithub| image:: https://github.com/mcmtroffaes/pybtex-docutils/actions/workflows/python-package.yml/badge.svg
:target: https://github.com/mcmtroffaes/pybtex-docutils/actions/workflows/python-package.yml
:alt: github-ci
.. |imagecodecov| image:: https://codecov.io/gh/mcmtroffaes/pybtex-docutils/branch/develop/graph/badge.svg
:target: https://app.codecov.io/gh/mcmtroffaes/pybtex-docutils
:alt: codecov
Installation
------------
For use with Sphinx, simply install
`sphinxcontrib-bibtex <https://sphinxcontrib-bibtex.readthedocs.io/>`_.
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 <https://sphinxcontrib-bibtex.readthedocs.io/>`_
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:
.. code-block:: rest
See [Nelson1987]_ for an introduction to non-standard analysis.
.. simplebibliography:: refs.bib
where ``refs.bib`` might contain:
.. code-block::
@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:
.. code-block:: python
#!/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``.
Raw data
{
"_id": null,
"home_page": "https://github.com/mcmtroffaes/pybtex-docutils",
"name": "pybtex-docutils",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Matthias C. M. Troffaes",
"author_email": "matthias.troffaes@gmail.com",
"download_url": "http://pypi.python.org/pypi/pybtex-docutils",
"platform": "any",
"description": "Overview\r\n--------\r\n\r\nThe pybtex docutils backend allows `BibTeX <http://www.bibtex.org/>`_\r\ncitations to be inserted into documentation generated by\r\n`docutils <https://docutils.sourceforge.io/>`_.\r\n\r\n* Download: https://pypi.org/project/pybtex-docutils/#files\r\n\r\n* Documentation: https://pybtex-docutils.readthedocs.io/en/latest/\r\n\r\n* Development: http://github.com/mcmtroffaes/pybtex-docutils/\r\n\r\n.. |imagegithub| image:: https://github.com/mcmtroffaes/pybtex-docutils/actions/workflows/python-package.yml/badge.svg\r\n :target: https://github.com/mcmtroffaes/pybtex-docutils/actions/workflows/python-package.yml\r\n :alt: github-ci\r\n\r\n.. |imagecodecov| image:: https://codecov.io/gh/mcmtroffaes/pybtex-docutils/branch/develop/graph/badge.svg\r\n :target: https://app.codecov.io/gh/mcmtroffaes/pybtex-docutils\r\n :alt: codecov\r\n\r\nInstallation\r\n------------\r\n\r\nFor use with Sphinx, simply install\r\n`sphinxcontrib-bibtex <https://sphinxcontrib-bibtex.readthedocs.io/>`_.\r\n\r\nFor use with pure docutils,\r\ninstall the module with ``pip install pybtex_docutils``, or from\r\nsource using ``pip install -e .``.\r\n\r\nMinimal Example\r\n---------------\r\n\r\nFor use with Sphinx, refer to the\r\n`sphinxcontrib-bibtex <https://sphinxcontrib-bibtex.readthedocs.io/>`_\r\ndocumentation.\r\n\r\nFor use with pure docutils, the module exposes a new ``simplebibliography``\r\ndirective, which will generate a citation for every entry in the specified\r\nbib files.\r\nThis new directive is only intended\r\nfor simple single document workflows\r\nthat do not require the full power of Sphinx.\r\nYou need exactly one of these directives in your document,\r\nplaced at the location where you want the citations to appear\r\n(typically, at the end).\r\n\r\nFor example:\r\n\r\n.. code-block:: rest\r\n\r\n See [Nelson1987]_ for an introduction to non-standard analysis.\r\n\r\n .. simplebibliography:: refs.bib\r\n\r\nwhere ``refs.bib`` might contain:\r\n\r\n.. code-block::\r\n\r\n @Book{Nelson1987,\r\n author = {Edward Nelson},\r\n title = {Radically Elementary Probability Theory},\r\n publisher = {Princeton University Press},\r\n year = {1987}\r\n }\r\n\r\nNote that citation keys are used as labels. For this to work, it is thus\r\nnecessary that all keys in your bib file are valid citation labels for\r\ndocutils. In particular, they cannot contain colons.\r\nThis limitation is lifted in ``sphinxcontrib-bibtex``,\r\nwhich also provides many more citation features.\r\n\r\nTo use the directive, you have to write your own command script\r\n(there seems to be no other way currently to extend docutils). For instance:\r\n\r\n.. code-block:: python\r\n\r\n #!/usr/bin/env python3\r\n from docutils.parsers.rst import directives, Directive\r\n from docutils.core import publish_cmdline, default_description\r\n\r\n from pybtex_docutils import SimpleBibliography\r\n\r\n description = ('Like rst2html5.py, but with .. simplebibliography support'\r\n + default_description)\r\n\r\n if __name__ == '__main__':\r\n directives.register_directive(\"simplebibliography\", SimpleBibliography)\r\n publish_cmdline(writer_name='html5', description=description)\r\n\r\nYou can then run this command as if you would run ``rst2html5``.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A docutils backend for pybtex.",
"version": "1.0.3",
"project_urls": {
"Download": "http://pypi.python.org/pypi/pybtex-docutils",
"Homepage": "https://github.com/mcmtroffaes/pybtex-docutils"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "11b1ce1f4596211efb5410e178a803f08e59b20bedb66837dcf41e21c54f9ec1",
"md5": "01cc832ae35e23ef1248f03acff571b5",
"sha256": "8fd290d2ae48e32fcb54d86b0efb8d573198653c7e2447d5bec5847095f430b9"
},
"downloads": -1,
"filename": "pybtex_docutils-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01cc832ae35e23ef1248f03acff571b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6385,
"upload_time": "2023-08-22T06:43:20",
"upload_time_iso_8601": "2023-08-22T06:43:20.513659Z",
"url": "https://files.pythonhosted.org/packages/11/b1/ce1f4596211efb5410e178a803f08e59b20bedb66837dcf41e21c54f9ec1/pybtex_docutils-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-22 06:43:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mcmtroffaes",
"github_project": "pybtex-docutils",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "pybtex-docutils"
}
JSON
