Skip to content

Switch documentation to pydata-sphinx-theme #8708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Apr 26, 2025
Merged

Switch documentation to pydata-sphinx-theme #8708

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
d3b8bdd
try pydata-sphinx-theme with no other alterations
TomNicholas Feb 5, 2024
c9c8694
Update conf.py
dcherian Aug 22, 2024
64a6197
Update conf.py
dcherian Aug 22, 2024
0c254da
merge main
scottyhq Apr 20, 2025
9d72f9e
merge main, update theme settings
scottyhq Apr 21, 2025
9b968ce
remove custom styling for old theme
scottyhq Apr 21, 2025
43442c8
cleanup, fix autodoc warnings for common docstrings
scottyhq Apr 21, 2025
dbc612a
remove comments from debugging
scottyhq Apr 21, 2025
2bb6ca0
ensure matplotlib inline used in gallery notebooks
scottyhq Apr 24, 2025
bca8b5a
reorganize sections
scottyhq Apr 24, 2025
db24e34
try jupyter_sphinx in overview for html rprs
scottyhq Apr 24, 2025
46c2195
promote release-notes to navbar, create seperate social media section
scottyhq Apr 25, 2025
ce7b38c
Merge branch 'main' into pydata-sphinx-theme
dcherian Apr 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions ci/requirements/doc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,49 +4,49 @@ channels:
- conda-forge
- nodefaults
dependencies:
- python=3.12
- python
- bottleneck
- cartopy
- cfgrib
- kerchunk
- dask-core>=2022.1
- hypothesis>=6.75.8
- h5netcdf>=0.13
- dask-core
- hypothesis
- h5netcdf
- ipykernel
- ipywidgets # silence nbsphinx warning
- ipython
- iris>=2.3
- iris
- jupyter_client
- matplotlib-base
- nbsphinx
- ncdata
- netcdf4>=1.5
- netcdf4
- numba
- numpy>=2
- packaging>=23.2
- pandas>=1.4,!=2.1.0
- packaging
- pandas
- pooch
- pip
- pre-commit
- pyarrow
- pydata-sphinx-theme
- pyproj
- rich # for Zarr tree()
- scipy!=1.10.0
- scipy
- seaborn
- setuptools
- sparse
- sphinx-autosummary-accessors
- sphinx-book-theme<=1.0.1
- sphinx-copybutton
- sphinx-design
- sphinx-inline-tabs
- sphinx>=5.0,<7.0 # https://github.com/executablebooks/sphinx-book-theme/issues/749
- sphinx>=6,<8
- sphinxcontrib-mermaid
- sphinxcontrib-srclinks
- sphinx-remove-toctrees
- sphinxext-opengraph
- sphinxext-rediraffe
- zarr>=2.10
- zarr
- pip:
- sphinxcontrib-mermaid
# relative to this file. Needs to be editable to be accepted.
- -e ../..
264 changes: 0 additions & 264 deletions doc/_static/style.css
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe most of this is making adjustments to the previous theme, and I found that simply removing most of it does fix #10223 (the issue of strange sidebar behavior with varying theme size). You can see that is remedied by making this browser window narrower https://xray--8708.org.readthedocs.build/en/8708/getting-started-guide/quick-overview.html

Original file line number Diff line number Diff line change
@@ -1,267 +1,3 @@
table.colwidths-given {
table-layout: fixed;
width: 100%;
}
table.docutils td {
white-space: unset;
word-wrap: break-word;
}

.bd-header-announcement {
background-color: var(--pst-color-info-bg);
}

/* Reduce left and right margins */

.container,
.container-lg,
.container-md,
.container-sm,
.container-xl {
max-width: 1350px !important;
}

/* Copied from
https://github.com/bokeh/bokeh/blob/branch-2.4/sphinx/source/bokeh/static/custom.css
*/

:root {
/* Logo image height + all the paddings/margins make the navbar height. */
--navbar-height: calc(30px + 0.3125rem * 2 + 0.5rem * 2);
}

.bd-search {
position: relative;
padding-bottom: 20px;
}

@media (min-width: 768px) {
.search-front-page {
width: 50%;
}
}

/* minimal copy paste from bootstrap docs css to get sidebars working */

.bd-toc {
-ms-flex-order: 2;
order: 2;
padding-top: 1.5rem;
padding-bottom: 1.5rem;
/* font-size: 0.875rem; */
/* add scrolling sidebar */
height: calc(100vh - 2rem);
overflow-y: auto;
}

@supports ((position: -webkit-sticky) or (position: sticky)) {
.bd-toc {
position: -webkit-sticky;
position: sticky;
top: 4rem;
height: calc(100vh - 4rem);
overflow-y: auto;
}
}

.section-nav {
padding-left: 0;
border-left: 1px solid #eee;
border-bottom: none;
}

.section-nav ul {
padding-left: 1rem;
}

.toc-entry {
display: block;
}

.toc-entry a {
display: block;
padding: 0.125rem 1.5rem;
color: #77757a;
}

.toc-entry a:hover {
color: rgba(0, 0, 0, 0.85);
text-decoration: none;
}

.bd-sidebar {
-ms-flex-order: 0;
order: 0;
border-bottom: 1px solid rgba(0, 0, 0, 0.1);
}

@media (min-width: 768px) {
.bd-sidebar {
border-right: 1px solid rgba(0, 0, 0, 0.1);
}
@supports ((position: -webkit-sticky) or (position: sticky)) {
.bd-sidebar {
position: -webkit-sticky;
position: sticky;
top: var(--navbar-height);
z-index: 1000;
height: calc(100vh - var(--navbar-height));
}
}
}

@media (min-width: 1200px) {
.bd-sidebar {
-ms-flex: 0 1 320px;
flex: 0 1 320px;
}
}

.bd-links {
padding-top: 1rem;
padding-bottom: 1rem;
margin-right: -15px;
margin-left: -15px;
}

@media (min-width: 768px) {
@supports ((position: -webkit-sticky) or (position: sticky)) {
.bd-links {
max-height: calc(100vh - 9rem);
overflow-y: auto;
}
}
}

@media (min-width: 768px) {
.bd-links {
display: block !important;
}
}

.bd-sidenav {
display: none;
}

.bd-toc-link {
display: block;
padding: 0.25rem 1.5rem;
font-weight: 400;
color: rgba(0, 0, 0, 0.65);
}

.bd-toc-link:hover {
color: rgba(0, 0, 0, 0.85);
text-decoration: none;
}

.bd-toc-item.active {
margin-bottom: 1rem;
}

.bd-toc-item.active:not(:first-child) {
margin-top: 1rem;
}

.bd-toc-item.active > .bd-toc-link {
color: rgba(0, 0, 0, 0.85);
}

.bd-toc-item.active > .bd-toc-link:hover {
background-color: transparent;
}

.bd-toc-item.active > .bd-sidenav {
display: block;
}

.bd-sidebar .nav > li > a {
display: block;
padding: 0.25rem 1.5rem;
font-size: 90%;
}

.bd-sidebar .nav > li > a:hover {
text-decoration: none;
background-color: transparent;
}

.bd-sidebar .nav > .active > a,
.bd-sidebar .nav > .active:hover > a {
font-weight: 400;
/* adjusted from original
color: rgba(0, 0, 0, 0.85);
background-color: transparent; */
}

.bd-sidebar .nav > li > ul {
list-style: none;
padding: 0.25rem 1.5rem;
}

.bd-sidebar .nav > li > ul > li > a {
display: block;
padding: 0.25rem 1.5rem;
font-size: 90%;
}

.bd-sidebar .nav > li > ul > .active > a,
.bd-sidebar .nav > li > ul > .active:hover > a {
font-weight: 400;
}

dt:target {
background-color: initial;
}

/* Offsetting anchored elements within the main content to adjust for fixed header
https://github.com/pandas-dev/pandas-sphinx-theme/issues/6 */
main *:target::before {
display: block;
content: "";
height: var(--navbar-height);
margin-top: calc(-1 * var(--navbar-height));
}

body {
width: 100%;
}

/* adjust toc font sizes to improve overview */
.toc-h2 {
font-size: 0.85rem;
}

.toc-h3 {
font-size: 0.75rem;
}

.toc-h4 {
font-size: 0.65rem;
}

.toc-entry > .nav-link.active {
font-weight: 400;
color: #542437;
background-color: transparent;
border-left: 2px solid #563d7c;
}

.nav-link:hover {
border-style: none;
}

/* Collapsing of the TOC sidebar while scrolling */

/* Nav: hide second level (shown on .active) */
.bd-toc .nav .nav {
display: none;
}

.bd-toc .nav > .active > ul {
display: block;
}

/* Main index page overview cards */

.sd-card-img-top {
Expand Down
6 changes: 3 additions & 3 deletions doc/api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1655,9 +1655,9 @@ Exceptions raised when manipulating trees.
.. autosummary::
:toctree: generated/

xarray.TreeIsomorphismError
xarray.InvalidTreeError
xarray.NotFoundInTreeError
TreeIsomorphismError
InvalidTreeError
NotFoundInTreeError

Advanced API
============
Expand Down
Loading
Loading