Sourcing BibTeX files from GitHub#

For documentation that references published documents, it’s useful formally cite references in additional to the typical practice of linking directly to other webpages. In the Sphinx documentation system, a good workflow is to code bibliographic references through standard BibTeX files and then reference items in those BibTeX files with the sphinxcontrib-bibtex extension. At Rubin Observatory, we maintain a centralized set of BibTeX files in the lsst/lsst-texmf repository. Documenteer provides a Sphinx extension, documenteer.ext.githubbibcache, that downloads BibTeX files from one or more GitHub repositories, caches them, and automatically configures sphinxcontrib-bibtex to use those BibTeX files. This page explains how to set up documenteer.ext.githubbibcache in your Sphinx documentation project and use it in conjunction with the sphinxcontrib-bibtex extension.


If you’re using one of the Documenteer configuration presets for Rubin Observatory documents, your Sphinx project is already configured to use lsst/lsst-texmf bibliography files. All you need to do is use the sphinxcontrib-bibtex extension’s citation roles and ensure that a bibliography directive is present in your documentation project.

Extension set up#

The extension from Documenteer needs to be loaded _before_ the sphinxcontrib-bibtex extension because it adds configurations that are later used by sphinxcontrib-bibtex. In your project’s file, set up the extensions like this:
extensions = [


If you’re using BibTeX files from lsst/lsst-texmf, you’ll need to set also add an extension that supports Rubin Observatory’s custom @DocuShare BibTeX entry type through BibTeX style extension for Rubin Observatory. This configuration is then:
extensions = [

bibtex_default_style = "lsst_aa"

The style configuration specifies the style provided by documenteer.ext.bibtex.

Specify the GitHub repositories and their BibTeX files#

In, you’ll need to specify the GitHub repositories and their BibTeX files that you want to use. The documenteer_bibfile_github_repos variable is a list of dictionaries, where each dictionary has the following keys:

  • repo: the GitHub repository name, e.g., lsst/lsst-texmf.

  • ref: the Git reference (branch, tag, or commit hash) to use, e.g., main.

  • bibfiles: a list of paths to BibTeX files to download from the repository, e.g., ['texmf/bibtex/bib/refs.bib', 'texmf/bibtex/bib/lsst.bib'].

This is a sample configuration used in by Rubin Observatory’s technote configuration:
documenteer_bibfile_cache_dir = ".technote/bibfiles"
documenteer_bibfile_github_repos = [
        "repo": "lsst/lsst-texmf",
        "ref": "main",
        "bibfiles": [
# Set up bibtex_bibfiles
bibtex_bibfiles = []

# Automatically load local bibfiles in the root directory.
for p in Path.cwd().glob("*.bib"):

bibtex_default_style = "lsst_aa"
bibtex_reference_style = "author_year"

Create a bibliography and make citations#

The extension, documenteer.ext.githubbibcache, configures sphinxcontrib-bibtex to use the specified BibTeX files from GitHub. Now you can use sphinxcontrib-bibtex as normal in your documentation project.

First, ensure there’s a bibliography directive in your documentation project:


.. bibliography::

Then, you can use the citation roles provided by sphinxcontrib-bibtex.

Regular citations are made with the cite role, and textual citations are made with the cite:t role:

Rubin Observatory is a large astronomical survey telescope that will be
used to study the Universe :cite:`2019ApJ...873..111I`.

The Science Book :cite:t:`2009arXiv0912.0201L` describes the science goals
of Rubin Observatory.

Clearing the BibTeX cache#

By default, the extension caches the BibTeX files in a directory called _build/bibfile-cache relative to your project’s file. You can also customize this directory by setting the documenteer_bibfile_cache_dir variable in For example, Documenteer’s technote configuration sets this variable to .technote/bibfiles. To get new copies of the bibtex files from GitHub, you can delete the cache directory and rebuild your documentation project.