docs: Change docs theme to PyData Sphinx theme (#2513)

* Switch docs theme to use the PyData Sphinx theme which is used across the
  broader Scientific Python community ubiquitously.
   - Replace sphinx-rtd-theme with pydata-sphinx-theme in 'docs' extra.
* Reorder the navigation bar to keep API reference sections visible by default.
* Remove 'View me on GitHub' ribbon.
   - The ribbon will cause issues with the theme and isn't needed anymore.
* Add Melissa Weber Mendonça to contributors list.

docs/conf.py

@@ -55,7 +55,6 @@ def setup(app):
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx.ext.intersphinx',
-    'sphinx_rtd_theme',
     'sphinxcontrib.bibtex',
     'sphinx.ext.napoleon',
     'sphinx_click.ext',
@@ -243,13 +242,13 @@ def setup(app):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {}
+html_theme_options = {"header_links_before_dropdown": 6}
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = []

docs/contributors.rst

@@ -34,3 +34,4 @@ Contributors include:
 - Daniel Werner
 - Jonas Rembser
 - Lorenz Gaertner
+- Melissa Weber Mendonça

docs/index.rst

@@ -8,25 +8,20 @@
 
    intro
    likelihood
-   learn
    examples
-   outreach
+   api
+   cli
    installation
    development
    faq
+   learn
    babel
-   cli
-   api
+   outreach
    citations
    governance/ROADMAP
    release-notes
    contributors
 
-.. raw:: html
-
-   <a class="github-fork-ribbon right-top fixed" href="https://github.com/scikit-hep/pyhf/" data-ribbon="View me on GitHub" title="View me on GitHub">View me on GitHub</a>
-
-
 .. raw:: html
 
    <p id="dev-version"><strong>Warning:</strong> This is a development version. The latest stable version is at <a href="https://pyhf.readthedocs.io/">ReadTheDocs</a>.</p>

pyproject.toml

@@ -118,7 +118,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.0",  # c.f. https://github.com/scikit-hep/pyhf/pull/2271
+    "pydata-sphinx-theme>=0.15.3",
     "nbsphinx!=0.8.8",  # c.f. https://github.com/spatialaudio/nbsphinx/issues/620
     "ipywidgets",
     "sphinx-issues",