sphinxcontrib-bibtex
====================
|ci| |codecov| |version| |license|
Sphinx extension for BibTeX style citations.
Overview
--------
The bibtex extension allows `BibTeX <http://www.bibtex.org/>`_
citations to be inserted into documentation generated by
`Sphinx <https://www.sphinx-doc.org/en/master/>`_, via
a ``bibliography`` directive,
along with ``:cite:p:`` and ``:cite:t:`` roles.
These work similarly to LaTeX's ``thebibliography`` environment
and the ``\citet`` and ``\citep`` commands.
For formatting, the extension relies on
`pybtex <https://pybtex.org/>`_
written by Andrey Golovizin.
The extension is inspired by Matthew Brett's
`bibstuff.sphinxext.bibref <https://github.com/matthew-brett/bibstuff>`_
and Weston Nielson's
`sphinx-natbib <https://github.com/mcmtroffaes/sphinxcontrib-bibtex/blob/develop/test/natbib.py>`_.
* Download: https://pypi.org/project/sphinxcontrib-bibtex/#files
* Documentation: https://sphinxcontrib-bibtex.readthedocs.io/en/latest/
* Development: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/
.. |ci| image:: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/actions/workflows/build.yml/badge.svg
:target: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/actions/workflows/build.yml
:alt: ci
.. |codecov| image:: https://codecov.io/gh/mcmtroffaes/sphinxcontrib-bibtex/branch/develop/graph/badge.svg
:target: https://app.codecov.io/gh/mcmtroffaes/sphinxcontrib-bibtex
:alt: codecov
.. |version| image:: https://img.shields.io/pypi/v/sphinxcontrib-bibtex.svg
:target: https://pypi.org/project/sphinxcontrib-bibtex/
:alt: latest version
.. |license| image:: https://img.shields.io/pypi/l/sphinxcontrib-bibtex.svg
:target: https://pypi.org/project/sphinxcontrib-bibtex/
:alt: license
Installation
------------
Install the module with ``pip install sphinxcontrib-bibtex``, or from
source using ``pip install -e .``. Then add:
.. code-block:: python
extensions = ['sphinxcontrib.bibtex']
bibtex_bibfiles = ['refs.bib']
to your project's Sphinx configuration file ``conf.py``.
Installation with ``python setup.py install`` is discouraged due to potential
issues with the sphinxcontrib namespace.
Minimal Example
---------------
In your project's documentation, you can use
``:cite:t:`` for textual citation references,
``:cite:p:`` for parenthetical citation references,
and ``.. bibliography::`` for inserting the bibliography.
For `example <https://github.com/mcmtroffaes/sphinxcontrib-bibtex/tree/develop/test/roots/test-debug_minimal_example>`_:
.. code-block:: rest
See :cite:t:`1987:nelson` for an introduction to non-standard analysis.
Non-standard analysis is fun :cite:p:`1987:nelson`.
.. bibliography::
where ``refs.bib`` would contain an entry::
@Book{1987:nelson,
author = {Edward Nelson},
title = {Radically Elementary Probability Theory},
publisher = {Princeton University Press},
year = {1987}
}
In the default style, this will get rendered as:
See Nelson [Nel87a]_ for an introduction to non-standard analysis.
Non-standard analysis is fun [Nel87a]_.
.. [Nel87a] Edward Nelson. *Radically Elementary Probability Theory*. Princeton University Press, 1987.
Citations in sphinx are resolved globally across all documents.
Typically, you have a single ``bibliography`` directive across
your entire project which collects all citations.
Advanced use cases with multiple ``bibliography`` directives
across your project are also supported, but some care
needs to be taken from your end to avoid duplicate citations.
In contrast, footnotes in sphinx are resolved locally per document.
To achieve local bibliographies per document, you can use citations
represented by footnotes as follows:
.. code-block:: rest
See :footcite:t:`1987:nelson` for an introduction to non-standard analysis.
Non-standard analysis is fun\ :footcite:p:`1987:nelson`.
.. footbibliography::
which will get rendered as:
See Nelson\ [#Nel87b]_ for an introduction to non-standard analysis.
Non-standard analysis is fun\ [#Nel87b]_.
.. [#Nel87b] Edward Nelson. *Radically Elementary Probability Theory*. Princeton University Press, 1987.
Note the use of the
`backslash escaped space <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#inline-markup>`_
to suppress the space that would otherwise precede the footnote.
Typically, you have a single ``footbibliography`` directive
at the bottom of each document that has footnote citations.
Advanced use cases with multiple ``footbibliography`` directives
per document are also supported. Since everything is local,
there is no concern with duplicate citations when using footnotes.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinxcontrib-bibtex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Matthias C. M. Troffaes",
"author_email": "matthias.troffaes@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c1/ce/054a8ec04063f9a27772fea7188f796edbfa382e656d3b76428323861f0e/sphinxcontrib_bibtex-2.6.3.tar.gz",
"platform": null,
"description": "sphinxcontrib-bibtex\n====================\n\n|ci| |codecov| |version| |license|\n\nSphinx extension for BibTeX style citations.\n\nOverview\n--------\n\nThe bibtex extension allows `BibTeX <http://www.bibtex.org/>`_\ncitations to be inserted into documentation generated by\n`Sphinx <https://www.sphinx-doc.org/en/master/>`_, via\na ``bibliography`` directive,\nalong with ``:cite:p:`` and ``:cite:t:`` roles.\nThese work similarly to LaTeX's ``thebibliography`` environment\nand the ``\\citet`` and ``\\citep`` commands.\n\nFor formatting, the extension relies on\n`pybtex <https://pybtex.org/>`_\nwritten by Andrey Golovizin.\nThe extension is inspired by Matthew Brett's\n`bibstuff.sphinxext.bibref <https://github.com/matthew-brett/bibstuff>`_\nand Weston Nielson's\n`sphinx-natbib <https://github.com/mcmtroffaes/sphinxcontrib-bibtex/blob/develop/test/natbib.py>`_.\n\n* Download: https://pypi.org/project/sphinxcontrib-bibtex/#files\n\n* Documentation: https://sphinxcontrib-bibtex.readthedocs.io/en/latest/\n\n* Development: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/\n\n.. |ci| image:: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/actions/workflows/build.yml/badge.svg\n :target: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/actions/workflows/build.yml\n :alt: ci\n\n.. |codecov| image:: https://codecov.io/gh/mcmtroffaes/sphinxcontrib-bibtex/branch/develop/graph/badge.svg\n :target: https://app.codecov.io/gh/mcmtroffaes/sphinxcontrib-bibtex\n :alt: codecov\n\n.. |version| image:: https://img.shields.io/pypi/v/sphinxcontrib-bibtex.svg\n :target: https://pypi.org/project/sphinxcontrib-bibtex/\n :alt: latest version\n\n.. |license| image:: https://img.shields.io/pypi/l/sphinxcontrib-bibtex.svg\n :target: https://pypi.org/project/sphinxcontrib-bibtex/\n :alt: license\n\nInstallation\n------------\n\nInstall the module with ``pip install sphinxcontrib-bibtex``, or from\nsource using ``pip install -e .``. Then add:\n\n.. code-block:: python\n\n extensions = ['sphinxcontrib.bibtex']\n bibtex_bibfiles = ['refs.bib']\n\nto your project's Sphinx configuration file ``conf.py``.\n\nInstallation with ``python setup.py install`` is discouraged due to potential\nissues with the sphinxcontrib namespace.\n\nMinimal Example\n---------------\n\nIn your project's documentation, you can use\n``:cite:t:`` for textual citation references,\n``:cite:p:`` for parenthetical citation references,\nand ``.. bibliography::`` for inserting the bibliography.\nFor `example <https://github.com/mcmtroffaes/sphinxcontrib-bibtex/tree/develop/test/roots/test-debug_minimal_example>`_:\n\n.. code-block:: rest\n\n See :cite:t:`1987:nelson` for an introduction to non-standard analysis.\n Non-standard analysis is fun :cite:p:`1987:nelson`.\n\n .. bibliography::\n\nwhere ``refs.bib`` would contain an entry::\n\n @Book{1987:nelson,\n author = {Edward Nelson},\n title = {Radically Elementary Probability Theory},\n publisher = {Princeton University Press},\n year = {1987}\n }\n\nIn the default style, this will get rendered as:\n\nSee Nelson [Nel87a]_ for an introduction to non-standard analysis.\nNon-standard analysis is fun [Nel87a]_.\n\n.. [Nel87a] Edward Nelson. *Radically Elementary Probability Theory*. Princeton University Press, 1987.\n\nCitations in sphinx are resolved globally across all documents.\nTypically, you have a single ``bibliography`` directive across\nyour entire project which collects all citations.\nAdvanced use cases with multiple ``bibliography`` directives\nacross your project are also supported, but some care\nneeds to be taken from your end to avoid duplicate citations.\n\nIn contrast, footnotes in sphinx are resolved locally per document.\nTo achieve local bibliographies per document, you can use citations\nrepresented by footnotes as follows:\n\n.. code-block:: rest\n\n See :footcite:t:`1987:nelson` for an introduction to non-standard analysis.\n Non-standard analysis is fun\\ :footcite:p:`1987:nelson`.\n\n .. footbibliography::\n\nwhich will get rendered as:\n\nSee Nelson\\ [#Nel87b]_ for an introduction to non-standard analysis.\nNon-standard analysis is fun\\ [#Nel87b]_.\n\n.. [#Nel87b] Edward Nelson. *Radically Elementary Probability Theory*. Princeton University Press, 1987.\n\nNote the use of the\n`backslash escaped space <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#inline-markup>`_\nto suppress the space that would otherwise precede the footnote.\n\nTypically, you have a single ``footbibliography`` directive\nat the bottom of each document that has footnote citations.\nAdvanced use cases with multiple ``footbibliography`` directives\nper document are also supported. Since everything is local,\nthere is no concern with duplicate citations when using footnotes.\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "Sphinx extension for BibTeX style citations.",
"version": "2.6.3",
"project_urls": {
"homepage": "https://github.com/mcmtroffaes/sphinxcontrib-bibtex"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8e49c23f9493c0a5d5881fb7ed3002e87708454fef860aa96a48e755d27bf6f0",
"md5": "be0336cb4cbbdcc0bfaf0d827ac4517d",
"sha256": "ff016b738fcc867df0f75c29e139b3b2158d26a2c802db27963cb128be3b75fb"
},
"downloads": -1,
"filename": "sphinxcontrib_bibtex-2.6.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be0336cb4cbbdcc0bfaf0d827ac4517d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 40340,
"upload_time": "2024-09-12T14:23:43",
"upload_time_iso_8601": "2024-09-12T14:23:43.593495Z",
"url": "https://files.pythonhosted.org/packages/8e/49/c23f9493c0a5d5881fb7ed3002e87708454fef860aa96a48e755d27bf6f0/sphinxcontrib_bibtex-2.6.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c1ce054a8ec04063f9a27772fea7188f796edbfa382e656d3b76428323861f0e",
"md5": "7b77b633910b9a1895616acd79804062",
"sha256": "7c790347ef1cb0edf30de55fc324d9782d085e89c52c2b8faafa082e08e23946"
},
"downloads": -1,
"filename": "sphinxcontrib_bibtex-2.6.3.tar.gz",
"has_sig": false,
"md5_digest": "7b77b633910b9a1895616acd79804062",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 117177,
"upload_time": "2024-09-12T14:23:44",
"upload_time_iso_8601": "2024-09-12T14:23:44.662943Z",
"url": "https://files.pythonhosted.org/packages/c1/ce/054a8ec04063f9a27772fea7188f796edbfa382e656d3b76428323861f0e/sphinxcontrib_bibtex-2.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-12 14:23:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mcmtroffaes",
"github_project": "sphinxcontrib-bibtex",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "sphinxcontrib-bibtex"
}
JSON
