docs: Use sphinxcontrib-bibtex v2.1 and bibtex_bibfiles setting

[matthewfeickert]

Description

Require sphinxcontrib-bibtex releases compatible with v2.0, which requires the definition of the bibtex_bibfiles in the Sphinx conf.py. With v2.0 Sphinx must be run twice to generate the bibliography:

It is good to be aware that the extension stores all citation information in a bibtex.json file in the source folder. If it does not exist, the file will be created on your first sphinx build, and you will have to rerun the build to make use of it. The file is automatically kept up to date, with a warning whenever you need to rerun the build (i.e. whenever your citations change). The file can be stored in version control if you do not want your users to have to run sphinx twice when they clone your project, or when you need your documentation to be built on an external service which only runs sphinx once.

Require sphinxcontrib-bibtex releases compatible with v2.1, which requires the definition of the bibtex_bibfiles in the Sphinx conf.py, thanks to mcmtroffaes/sphinxcontrib-bibtex#219 making the sphinxcontrib-bibtex v2.1 release series able to run with a single pass through a Sphinx build. 🎉

Requires PR #1220 to go in first.

ReadTheDocs build: https://pyhf.readthedocs.io/en/docs-use-sphinxcontrib-bibtex-v2.0/

Checklist Before Requesting Reviewer

• Tests are passing
• "WIP" removed from the title of the pull request
• Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* Require sphinxcontrib-bibtex releases compatible with v2.1
* Add bibtex_bibfiles list to Sphinx conf.py
* Update RTD to Python 3.8 runtime

[codecov]

Codecov Report

Merging #1221 (b45c8c4) into master (1f15258) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1221   +/-   ##
=======================================
  Coverage   97.47%   97.47%           
=======================================
  Files          63       63           
  Lines        3716     3716           
  Branches      525      525           
=======================================
  Hits         3622     3622           
  Misses         55       55           
  Partials       39       39           

Flag	Coverage Δ
unittests	97.47% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1f15258...b45c8c4. Read the comment docs.

[matthewfeickert]

With v2.0 Sphinx must be run twice to generate the bibliography

I don't know how to get this to work on the RTD tests.

[matthewfeickert]

With v2.0 Sphinx must be run twice to generate the bibliography

I don't know how to get this to work on the RTD tests.

All issues are resolved with sphinxcontrib-bibtex v2.1.