About

This Sphinx extension (named “sphinx-bibtexpdflink”, parsed as “bibtex pdf link”) adds a link to a PDF file and a link to a “notes” file (source is a .rst file) to citations generated by the sphinxcontrib-bibtex extension and sphinxcontrib-bibtex2 extension (which is included with the sphinxcontrib-bibtex extension).

The purpose of adding these links is to allow someone viewing a citation to readily open a PDF file containing the publication the citation is for, and also open a file containing notes about the publication.

The extension works by adding two options to the Sphinx configuration file conf.py. These options specify the directories containing the PDF files and the notes files. The names of the PDF and notes files must be the same as the bibtex citation key, but with extension “.pdf” (for the PDF file) and “.rst” for the note file. When generating the citation, these directories are checked for the PDF and note file, and if found, the links to the files are added to the citation. If the citation is being included within a note file, then the link to the note will not be generated (since it links to the file itself), but instead just the name of the file (and not a link) is displayed along with the text “(this file).”

Installing this extension automatically installs both sphinxcontrib-bibtex and sphinxcontrib-bibtex2 . The former is installed from the Python Package Index (PyPI); the entry is: https://pypi.org/project/sphinxcontrib-bibtex/ ). The latter (bibtex2) cannot currently be installed from PyPI because, although it is included in the bibtex code that is in github, it is not currently included in the version of bibtex (version 1.0.0) at PiPY. So, bibtex2 it is included with this package. (It was copied from the bibtex github repository and added to this package). If a future version of bibtex on PyPI does include bibtex2, then it (bibtex2) could be removed from this package, and it would be installed from PyPI when sphinxcontrib-bibtex is installed.