Required Documenteer 0.4.3 upgrade for Sphinx technotes + BibTeX bibliography usage

doc-dev
Tags: #<Tag:0x00007f7f6ff21a20>

(Jonathan Sick) #1

This message is for authors of Sphinx (reStructuredText) technotes. First, there is a required update to the requirements.txt file. Second, if you use the bibliography directive, there is an updated usage pattern. Read on for details.

1. Update documenteer

You need to upgrade the version of Documenteer that builds your technote.

In the requirements.txt file in the technote’s Git repository, set the documenteer dependency to:

documenteer[technote]>=0.4.3,<0.5.0

This new version of Documenteer will ensure that sphinxcontrib-bibtex is compatible with the pinned version of Sphinx.

2. Updated usage of the bibliography directive

In the past, we recommended that you have an encoding field in the bibliography directive. With recent changes to sphinxcontrib-bibtex this is no longer the case — you actually can’t use the latex+latin encoding at all!

The new usage is:

.. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib
   :style: lsst_aa