docs(backport): Update docs requirements and use citations (#2320)

* Backport:
   - PR #2291
   - PR #2300
   - PR #2306
   - PR #2308
   - PR #2309
   - PR #2312
   - PR #2315
   - PR #2316

.github/ISSUE_TEMPLATE/~release-checklist.md

@@ -7,17 +7,17 @@ about: Checklist for core developers to complete as part of making a release
 
 ## Before Release
 
+* [ ] Update the checklist Issue template in the [``.github/ISSUE_TEMPLATE``](https://github.com/scikit-hep/pyhf/tree/main/.github/ISSUE_TEMPLATE) directory if there are revisions.
 * [ ] Migrate any unresolved Issues or PRs from the [release GitHub project board](https://github.com/scikit-hep/pyhf/projects/) to a new project board.
 * [ ] Verify that there is a release notes file for the release under [``docs/release-notes``](https://github.com/scikit-hep/pyhf/tree/main/docs/release-notes).
 * [ ] Verify that the release notes files correctly summarize all development changes since the last release.
-* [ ] Update the checklist Issue template in the [``.github/ISSUE_TEMPLATE``](https://github.com/scikit-hep/pyhf/tree/main/.github/ISSUE_TEMPLATE) directory if there are revisions.
 * [ ] Add any new use citations or published statistical models to the [Use and Citations page][citations_page].
 * [ ] Verify that the citations on the [Use and Citations page][citations_page] are up to date with their current [INSPIRE](https://inspirehep.net/) record. Checking the [Dimensions listing of publication citations](https://app.dimensions.ai/discover/publication?or_subset_publication_citations=pub.1135154020) can be helpful to catch citations that are now journal publications.
 * [ ] Update the ``codemeta.json`` file in the release PR if its requirements have updated.
 * [ ] Update the [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) GitHub Action used for deployment to TestPyPI and PyPI to the latest stable release.
 * [ ] Make a release to [TestPyPI][TestPyPI_pyhf] using the [workflow dispatch event trigger](https://github.com/scikit-hep/pyhf/actions/workflows/publish-package.yml).
 * [ ] Verify that the project README is displaying correctly on [TestPyPI][TestPyPI_pyhf].
-* [ ] Draft email to [``pyhf-announcements`` mailing list](https://groups.google.com/group/pyhf-announcements/subscribe) that summarizes the main points of the release notes and circulate it for development team approval.
+* [ ] Draft email to [``pyhf-announcements`` mailing list](https://groups.google.com/group/pyhf-announcements/) that summarizes the main points of the release notes and circulate it for development team approval.
 
 [TestPyPI_pyhf]: https://test.pypi.org/project/pyhf/
 [citations_page]: https://scikit-hep.org/pyhf/citations.html
@@ -48,18 +48,20 @@ For a video walkthrough consult the [``pyhf`` ``v0.7.1`` release recording](http
    - [ ] Verify that the new release archive metadata on Zenodo matches is being picked up as expected from [`CITATION.cff`](https://github.com/scikit-hep/pyhf/blob/main/CITATION.cff).
 * [ ] Verify that a Binder has properly built for the new release.
 * [ ] Watch for a GitHub notification that there is an automatic PR to the [Conda-forge feedstock](https://github.com/conda-forge/pyhf-feedstock). This may take multiple hours to happen. If there are any changes needed to the Conda-forge release make them **from a personal account** and not from an organization account to have workflows properly trigger.
-   - [ ] Check if any requirements need to be updated by commenting "@conda-grayskull show requirements" on the PR.
    - [ ] Verify the requirements in the [Conda-forge feedstock](https://github.com/conda-forge/pyhf-feedstock) recipe `meta.yaml` match those in `pyproject.toml`.
 
 ## After Release
 
 * [ ] Verify that the release is installable from both [PyPI](https://pypi.org/project/pyhf/) and [Conda-forge](https://github.com/conda-forge/pyhf-feedstock).
-* [ ] Send the drafted ``pyhf-announcements`` email out from the ``pyhf-announcements`` account email.
+* [ ] Send the drafted [``pyhf-announcements``](https://groups.google.com/group/pyhf-announcements/) email out from the ``pyhf-announcements`` account email.
 * [ ] Tweet the release out on both personal and team Twitter accounts.
+* [ ] Forward port the release notes and bumpversion information from the release branch to the default branch.
+   - c.f. PR https://github.com/scikit-hep/pyhf/pull/2217 and PR https://github.com/scikit-hep/pyhf/pull/2218 as examples from `pyhf` `v0.7.2`.
 * [ ] Announce the release on the [Scikit-HEP community Gitter](https://gitter.im/Scikit-HEP/community).
 * [ ] Make a release for the [`pyhf` tutorial](https://github.com/pyhf/pyhf-tutorial/releases) corresponding to the **previous release** number. This release represents the last version of the tutorial that is guaranteed to work with previous release API.
 * [ ] Update the [tutorial](https://github.com/pyhf/pyhf-tutorial) to use the new release number and API.
 * [ ] Make a PR to use the new release in the [CUDA enabled Docker images](https://github.com/pyhf/cuda-images).
 * [ ] Open a ticket on the CERN [Software Process and Infrastructure JIRA](https://sft.its.cern.ch/jira/browse/SPI) to update the version of `pyhf` available in the next LCG release.
-   - c.f. the [`v0.6.3` request ticket](https://sft.its.cern.ch/jira/browse/SPI-2086) and the [`v0.7.1` request ticket](https://sft.its.cern.ch/jira/browse/SPI-2333) as examples.
+   - c.f. the [`v0.7.3` request ticket](https://sft.its.cern.ch/jira/browse/SPI-2408) as an example.
+* [ ] Make a MR to use the new release in [ATLAS `StatAnalysis`](https://gitlab.cern.ch/atlas/StatAnalysis).
 * [ ] Close the [release GitHub Project board](https://github.com/scikit-hep/pyhf/projects/).

docs/bib/general_citations.bib

@@ -1,3 +1,15 @@
+% 2023-08-31
+@article{Kagan:2023gxz,
+    author = "Kagan, Michael and Heinrich, Lukas",
+    title = "{Branches of a Tree: Taking Derivatives of Programs with Discrete and Branching Randomness in High Energy Physics}",
+    eprint = "2308.16680",
+    archivePrefix = "arXiv",
+    primaryClass = "stat.ML",
+    month = "8",
+    year = "2023",
+    journal = ""
+}
+
 % 2023-06-06
 @article{Eschle:2023ikn,
     author = "Eschle, J. and others",

docs/bib/use_citations.bib

@@ -1,3 +1,24 @@
+% 2023-09-04
+@article{Fenton:2023ikr,
+    author = "Fenton, Michael James and Shmakov, Alexander and Okawa, Hideki and Li, Yuji and Hsiao, Ko-Yang and Hsu, Shih-Chieh and Whiteson, Daniel and Baldi, Pierre",
+    title = "{Extended Symmetry Preserving Attention Networks for LHC Analysis}",
+    eprint = "2309.01886",
+    archivePrefix = "arXiv",
+    primaryClass = "hep-ex",
+    month = "9",
+    year = "2023",
+    journal = ""
+}
+
+% 2023-08-18
+@booklet{ATLAS-CONF-2023-040,
+    author = "{ATLAS Collaboration}",
+    title = "{Search for short- and long-lived axion-like particles in $H\rightarrow a a \rightarrow 4\gamma$ decays with the ATLAS experiment at the LHC}",
+    howpublished = "{ATLAS-CONF-2023-040}",
+    url = "https://cds.cern.ch/record/2867933",
+    year = "2023"
+}
+
 % 2023-07-18
 @article{Darme:2023nsy,
     author = "Darm\'e, Luc and Deandrea, Aldo and Mahmoudi, Farvah",

docs/conf.py

@@ -519,6 +519,8 @@ def setup(app):
     r'https://indico.desy.de/event/22731/.*',
     # https://indico.belle2.org/event/8470/contributions/55871/ is frequently generating 403 Client Error
     r'https://indico.belle2.org/event/8470/.*',
+    # https://doi.org/10.1142/S0217732321020016 is frequently generating 403 Client Error
+    r'https://doi\.org/10.1142/.*',
     # CERN doesn't maintain its SSL certs well enough to not have SSLErrors
     r'https://twiki.cern.ch/.*',
     # tags for a release won't exist until it is made, but the release notes
@@ -529,4 +531,5 @@ def setup(app):
 linkcheck_retries = 50
 
 # JupyterLite configuration
-jupyterlite_dir = "lite"
+# Use Path as jupyterlite-sphinx expects PosixPath
+jupyterlite_dir = Path("lite")

pyproject.toml

@@ -111,7 +111,7 @@ docs = [
     "sphinx>=7.0.0",  # c.f. https://github.com/scikit-hep/pyhf/pull/2271
     "sphinxcontrib-bibtex~=2.1",
     "sphinx-click",
-    "sphinx-rtd-theme>=1.3.0rc1",  # c.f. https://github.com/scikit-hep/pyhf/pull/2271
+    "sphinx-rtd-theme>=1.3.0",  # c.f. https://github.com/scikit-hep/pyhf/pull/2271
     "nbsphinx!=0.8.8",  # c.f. https://github.com/spatialaudio/nbsphinx/issues/620
     "ipywidgets",
     "sphinx-issues",