From e8789a2a5233f1c4d825ef0daeec8434f6893146 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= <melissawm@gmail.com>
Date: Fri, 7 Jun 2024 00:45:27 -0700
Subject: [PATCH] docs: Change docs theme to PyData Sphinx theme (#2513)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 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          |  5 ++---
 docs/contributors.rst |  1 +
 docs/index.rst        | 13 ++++---------
 pyproject.toml        |  2 +-
 4 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 132f4da544..801ef81cef 100644
--- a/docs/conf.py
+++ b/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 = []
diff --git a/docs/contributors.rst b/docs/contributors.rst
index d29fd0974b..292efde1c7 100644
--- a/docs/contributors.rst
+++ b/docs/contributors.rst
@@ -34,3 +34,4 @@ Contributors include:
 - Daniel Werner
 - Jonas Rembser
 - Lorenz Gaertner
+- Melissa Weber Mendonça
diff --git a/docs/index.rst b/docs/index.rst
index fbb5bf9925..7bddc7b269 100644
--- a/docs/index.rst
+++ b/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>
diff --git a/pyproject.toml b/pyproject.toml
index 6b53e2b5bc..52ae121b8f 100644
--- a/pyproject.toml
+++ b/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",