docs: Change docs theme to PyData Sphinx theme

[melissawm]

Description

This is a simple conversion of the documentation pages to the PyData Sphinx Theme using the default configurations for the theme.

From the documentation for the theme (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/readthedocs.html#version-switcher) the version switcher from readthedocs should still work after this is done (but won't show up before the PR is merged). If you want to use the version switcher of the PyData Sphinx Theme instead, it would require having urls for all of the previous versions of the library and one json file mapping urls to versions. This would also enable using the Version warning banner from the PyData theme itself: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/announcements.html#version-warning-banners

Closes #2512

Checklist Before Requesting Reviewer

• [N/A] 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

* 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.

[matthewfeickert]

Thanks @melissawm! This is great. :) As we talked about in person we might need to merge this to see if things work as expected on the RTD deployment RE: the version switcher, but I can also debug anything in follow up PRs.

@kratsg we should also consider moving things around in the ordering post this PR given that the API reference docs aren't immediately visible in the RTD preview (https://pyhf--2513.org.readthedocs.build/en/2513/).

[kratsg]

@kratsg we should also consider moving things around in the ordering post this PR given that the API reference docs aren't immediately visible in the RTD preview (https://pyhf--2513.org.readthedocs.build/en/2513/).

wonder why the API docs disappear?

[matthewfeickert]

wonder why the API docs disappear?

It isn't that they are gone, but just that the current docs deployment has them on a vertical bar on the left and the PyData Sphinx them has them on a horiztonal bar on the top.

vs.

[melissawm]

I believe we can reorganize the order in which those sections appear - let me make sure the API docs are more prominent in the navbar.

[matthewfeickert]

Thanks @melissawm. Though @kratsg and I could also do that in a follow up PR, as this PR gets things over the line in terms of being stylistically aligned with the rest of Scientific Python. 👍

[kratsg]

approved with the caveat of a follow-up to fix API docs

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.21%. Comparing base (7d316ef) to head (36c270c).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2513   +/-   ##
=======================================
  Coverage   98.21%   98.21%           
=======================================
  Files          69       69           
  Lines        4543     4543           
  Branches      804      804           
=======================================
  Hits         4462     4462           
  Misses         48       48           
  Partials       33       33           

Flag	Coverage Δ
contrib	97.79% <ø> (ø)
doctest	98.08% <ø> (ø)
unittests-3.10	96.23% <ø> (ø)
unittests-3.11	96.23% <ø> (ø)
unittests-3.12	96.23% <ø> (ø)
unittests-3.8	96.25% <ø> (ø)
unittests-3.9	96.27% <ø> (ø)

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

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[matthewfeickert]

Thanks for your PR @melissawm — your contributions are very appreciated!

[matthewfeickert]

From the documentation for the theme (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/readthedocs.html#version-switcher) the version switcher from readthedocs should still work after this is done (but won't show up before the PR is merged). If you want to use the version switcher of the PyData Sphinx Theme instead, it would require having urls for all of the previous versions of the library and one json file mapping urls to versions. This would also enable using the Version warning banner from the PyData theme itself: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/announcements.html#version-warning-banners

From https://pyhf.readthedocs.io/en/latest/ seems like we'll need the to use the PyData Sphinx Theme version switcher.