search

scikit-hep / pyhf

pure-Python HistFactory implementation with tensors and autodiff
https://pyhf.readthedocs.io/
Apache License 2.0
274 stars 81 forks source link

docs: Change docs theme to PyData Sphinx theme #2513

Closed melissawm closed 4 weeks ago

melissawm commented 4 weeks ago

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

Before Merging

For the PR Assignees:

* 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.
kratsg commented 4 weeks ago

@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 commented 4 weeks ago

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.

image

vs.

image

melissawm commented 4 weeks ago

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 commented 4 weeks ago

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. :+1:

codecov[bot] commented 4 weeks ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

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

Additional details and impacted files ```diff @@ 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](https://app.codecov.io/gh/scikit-hep/pyhf/pull/2513/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep) | Coverage Δ | | |---|---|---| | [contrib](https://app.codecov.io/gh/scikit-hep/pyhf/pull/2513/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep) | `97.79% <ø> (ø)` | | | [doctest](https://app.codecov.io/gh/scikit-hep/pyhf/pull/2513/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep) | `98.08% <ø> (ø)` | | | [unittests-3.10](https://app.codecov.io/gh/scikit-hep/pyhf/pull/2513/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep) | `96.23% <ø> (ø)` | | | [unittests-3.11](https://app.codecov.io/gh/scikit-hep/pyhf/pull/2513/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep) | `96.23% <ø> (ø)` | | | [unittests-3.12](https://app.codecov.io/gh/scikit-hep/pyhf/pull/2513/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep) | `96.23% <ø> (ø)` | | | [unittests-3.8](https://app.codecov.io/gh/scikit-hep/pyhf/pull/2513/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep) | `96.25% <ø> (ø)` | | | [unittests-3.9](https://app.codecov.io/gh/scikit-hep/pyhf/pull/2513/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep) | `96.27% <ø> (ø)` | | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=scikit-hep#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

matthewfeickert commented 4 weeks ago

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

matthewfeickert commented 4 weeks ago

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.