Add link to PDF and Note to citations generated by sphinxcontrib-bibtex¶

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.

Installation¶

Install the extension with:

$ pip install --index-url https://test.pypi.org/simple/ sphinxcontrib-bibtexpdflink

(This installs from Test PyPI).

The package is not yet on the real PyPI, but when it is, the installation command will be:

$ pip install sphinxcontrib-bibtexpdflink

Configuring¶

Add the extension to the Sphinx conf.py file (along with sphinxcontrib.bibtex and sphinxcontrib.bibtex2 extensions):

extensions = [
    "sphinxcontrib.bibtex",
    "sphinxcontrib.bibtex2",
    "sphinxcontrib.bibtexpdflink",
    ]

In the conf.py file, specify the directories for PDF and notes files using config variables bibtexpdflink_note_dir and bibtexpdflink_pdf_dir. An example is:

bibtexpdflink_note_dir = "notes"
bibtexpdflink_pdf_dir = "papers"

The directory specified for bibtexpdflink_pdf_dir must be inside the directory specified for html_static_path[0]. For example, if

html_static_path = ['_static']

and

bibtexpdflink_pdf_dir = "papers"

Then the pdf files must be placed in directory: _static/papers.

The directory specified for bibtexpdflink_note_dir must be directly inside the top-level Sphinx source directory (the same directory containing the Sphinx conf.py file).

The names of the pdf and notes files must be the same as the bibtex citation key, but respectively with extension “.pdf” and “.rst”.

Usage¶

Name the PDF files and notes files as described in Installation.

Use the normal bibtex or bibtex2 directives:

See :cite:`JaeckelLA-1989a` also :footcite:`JaeckelLA-1989a` for more details.

Some random text...

.. footbibliography::

This will be rendered as:

See [JaeckelLA-1989a] also 1 for more details.

Some random text…

1: LA Jaeckel. An alternative design for a sparse distributed memory. Technical Report 89.28, NASA Ames Research Center, 1989. PDF: JaeckelLA-1989a.pdf, Notes: JaeckelLA-1989a.html.

Generating a list of the notes¶

To generate a list of notes files, put an additional “.rst” file in the directory containing the notes (the name of the file could be “notes.rst”). Include in the file a toctree:: directive like in the following:

The following notes are available:

.. toctree::
   :glob:

   *

This will be rendered as shown on the Notes page.

Notes¶

The following notes are available:

JaeckelLA-1989a¶

Notes about [JaeckelLA-1989a] 1 .

This paper describes the “selected-coordinate design” of the Sparce Distributed Memory (SDM). The design was the subject of a patent application filed in 1998.

1: LA Jaeckel. An alternative design for a sparse distributed memory. Technical Report 89.28, NASA Ames Research Center, 1989. PDF: JaeckelLA-1989a.pdf, Notes: JaeckelLA-1989a.html (this file).

LiK+MalikJ-2017¶

Notes about [LiK+MalikJ-2017] 1 .

This paper describes an effecient algorithm for searching for k-nearest neighbours. It states that the algorithm is reduces the number of distance evaluations by a factor of 14 to 116 and the memory consumption by a factor of 21 compared to prior methods.

1: K Li and J Malik. Fast k-nearest neighbour search via dynamic continuous indexing. 2017. URL: https://arxiv.org/abs/1512.00442, PDF: LiK+MalikJ-2017.pdf, Notes: LiK+MalikJ-2017.html (this file).

LoebnerEE-1989¶

Notes about [LoebnerEE-1989] 1 .

Figure 2 in the paper provides data about the number of cells of different types in the cat cerebellum.

The number of cells of each type given in the figure is:

Cell type	Number of cells
basket	7.5x10^6
golgi	4.2x10^5
granule	“2.2x10^9
purkinje	1.3x10^6
stellate	2.1x10^7

1: EE Loebner. Intelligent network management and functional cerebellum synthesis. In Raugh MR, editor, Cerebellar Models of Associative Memory: Three papers from IEEE COMPCON SPRING ‘89, pages 14–19. Research Institute for Advanced Computer Science, NASA Ames Research Center, 1989. PDF: LoebnerEE-1989.pdf, Notes: LoebnerEE-1989.html (this file).