Skip to content

Commit 7426ce7

Browse files
TomNicholasdcherianscottyhq
authored
Switch documentation to pydata-sphinx-theme (#8708)
Co-authored-by: Deepak Cherian <[email protected]> Co-authored-by: Scott Henderson <[email protected]>
1 parent 90f0dd6 commit 7426ce7

24 files changed

+624
-786
lines changed

‎ci/requirements/doc.yml‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,49 +4,50 @@ channels:
44
- conda-forge
55
- nodefaults
66
dependencies:
7-
- python=3.12
7+
- python
88
- bottleneck
99
- cartopy
1010
- cfgrib
1111
- kerchunk
12-
- dask-core>=2022.1
13-
- hypothesis>=6.75.8
14-
- h5netcdf>=0.13
12+
- dask-core
13+
- hypothesis
14+
- h5netcdf
1515
- ipykernel
1616
- ipywidgets # silence nbsphinx warning
1717
- ipython
18-
- iris>=2.3
18+
- iris
1919
- jupyter_client
20+
- jupyter_sphinx
2021
- matplotlib-base
2122
- nbsphinx
2223
- ncdata
23-
- netcdf4>=1.5
24+
- netcdf4
2425
- numba
2526
- numpy>=2
26-
- packaging>=23.2
27-
- pandas>=1.4,!=2.1.0
27+
- packaging
28+
- pandas
2829
- pooch
2930
- pip
3031
- pre-commit
3132
- pyarrow
33+
- pydata-sphinx-theme
3234
- pyproj
3335
- rich # for Zarr tree()
34-
- scipy!=1.10.0
36+
- scipy
3537
- seaborn
3638
- setuptools
3739
- sparse
3840
- sphinx-autosummary-accessors
39-
- sphinx-book-theme<=1.0.1
4041
- sphinx-copybutton
4142
- sphinx-design
4243
- sphinx-inline-tabs
43-
- sphinx>=5.0,<7.0 # https://github.com/executablebooks/sphinx-book-theme/issues/749
44+
- sphinx>=6,<8
45+
- sphinxcontrib-mermaid
4446
- sphinxcontrib-srclinks
4547
- sphinx-remove-toctrees
4648
- sphinxext-opengraph
4749
- sphinxext-rediraffe
48-
- zarr>=2.10
50+
- zarr
4951
- pip:
50-
- sphinxcontrib-mermaid
5152
# relative to this file. Needs to be editable to be accepted.
5253
- -e ../..

‎doc/_static/style.css‎

Lines changed: 34 additions & 261 deletions
Original file line numberDiff line numberDiff line change
@@ -1,273 +1,46 @@
1-
table.colwidths-given {
2-
table-layout: fixed;
3-
width: 100%;
4-
}
5-
table.docutils td {
6-
white-space: unset;
7-
word-wrap: break-word;
8-
}
9-
10-
.bd-header-announcement {
11-
background-color: var(--pst-color-info-bg);
12-
}
13-
14-
/* Reduce left and right margins */
1+
/* Override some aspects of the pydata-sphinx-theme */
152

16-
.container,
17-
.container-lg,
18-
.container-md,
19-
.container-sm,
20-
.container-xl {
21-
max-width: 1350px !important;
22-
}
23-
24-
/* Copied from
25-
https://github.com/bokeh/bokeh/blob/branch-2.4/sphinx/source/bokeh/static/custom.css
3+
/* Xarray Branding Guide:
4+
Primary Color palette (Hex): #17afb4 #e28126 #59c7d6 #0e4666 #4a4a4a
5+
Secondary Color Palette (Hex): #f58154 #e7b72d #b3dfe5 #8e8d99 #767985
6+
Primary Typeface: Acumin Variable Concept - Semicondensed Medium
267
*/
278

28-
:root {
29-
/* Logo image height + all the paddings/margins make the navbar height. */
30-
--navbar-height: calc(30px + 0.3125rem * 2 + 0.5rem * 2);
31-
}
32-
33-
.bd-search {
34-
position: relative;
35-
padding-bottom: 20px;
36-
}
37-
38-
@media (min-width: 768px) {
39-
.search-front-page {
40-
width: 50%;
41-
}
42-
}
43-
44-
/* minimal copy paste from bootstrap docs css to get sidebars working */
45-
46-
.bd-toc {
47-
-ms-flex-order: 2;
48-
order: 2;
49-
padding-top: 1.5rem;
50-
padding-bottom: 1.5rem;
51-
/* font-size: 0.875rem; */
52-
/* add scrolling sidebar */
53-
height: calc(100vh - 2rem);
54-
overflow-y: auto;
55-
}
56-
57-
@supports ((position: -webkit-sticky) or (position: sticky)) {
58-
.bd-toc {
59-
position: -webkit-sticky;
60-
position: sticky;
61-
top: 4rem;
62-
height: calc(100vh - 4rem);
63-
overflow-y: auto;
64-
}
65-
}
66-
67-
.section-nav {
68-
padding-left: 0;
69-
border-left: 1px solid #eee;
70-
border-bottom: none;
71-
}
72-
73-
.section-nav ul {
74-
padding-left: 1rem;
75-
}
76-
77-
.toc-entry {
78-
display: block;
79-
}
80-
81-
.toc-entry a {
82-
display: block;
83-
padding: 0.125rem 1.5rem;
84-
color: #77757a;
85-
}
86-
87-
.toc-entry a:hover {
88-
color: rgba(0, 0, 0, 0.85);
89-
text-decoration: none;
90-
}
91-
92-
.bd-sidebar {
93-
-ms-flex-order: 0;
94-
order: 0;
95-
border-bottom: 1px solid rgba(0, 0, 0, 0.1);
96-
}
97-
98-
@media (min-width: 768px) {
99-
.bd-sidebar {
100-
border-right: 1px solid rgba(0, 0, 0, 0.1);
101-
}
102-
@supports ((position: -webkit-sticky) or (position: sticky)) {
103-
.bd-sidebar {
104-
position: -webkit-sticky;
105-
position: sticky;
106-
top: var(--navbar-height);
107-
z-index: 1000;
108-
height: calc(100vh - var(--navbar-height));
109-
}
110-
}
111-
}
112-
113-
@media (min-width: 1200px) {
114-
.bd-sidebar {
115-
-ms-flex: 0 1 320px;
116-
flex: 0 1 320px;
117-
}
118-
}
119-
120-
.bd-links {
121-
padding-top: 1rem;
122-
padding-bottom: 1rem;
123-
margin-right: -15px;
124-
margin-left: -15px;
125-
}
126-
127-
@media (min-width: 768px) {
128-
@supports ((position: -webkit-sticky) or (position: sticky)) {
129-
.bd-links {
130-
max-height: calc(100vh - 9rem);
131-
overflow-y: auto;
132-
}
133-
}
134-
}
135-
136-
@media (min-width: 768px) {
137-
.bd-links {
138-
display: block !important;
139-
}
140-
}
141-
142-
.bd-sidenav {
143-
display: none;
144-
}
145-
146-
.bd-toc-link {
147-
display: block;
148-
padding: 0.25rem 1.5rem;
149-
font-weight: 400;
150-
color: rgba(0, 0, 0, 0.65);
9+
/* Increase Xarray logo size in upper left corner */
10+
.navbar-brand img {
11+
height: 75px;
15112
}
152-
153-
.bd-toc-link:hover {
154-
color: rgba(0, 0, 0, 0.85);
155-
text-decoration: none;
13+
.navbar-brand {
14+
height: 75px;
15615
}
15716

158-
.bd-toc-item.active {
159-
margin-bottom: 1rem;
17+
/* Adjust index page overview cards, borrowed from Pandas & Numpy */
18+
/* Override SVG icon color */
19+
html[data-theme="dark"] .sd-card img[src*=".svg"] {
20+
filter: invert(0.82) brightness(0.8) contrast(1.2);
16021
}
161-
162-
.bd-toc-item.active:not(:first-child) {
163-
margin-top: 1rem;
22+
/* https://github.com/executablebooks/sphinx-design/blob/main/style/_cards.scss */
23+
/* More space around image */
24+
.intro-card {
25+
padding: 30px 1px 1px 1px;
16426
}
165-
166-
.bd-toc-item.active > .bd-toc-link {
167-
color: rgba(0, 0, 0, 0.85);
27+
/* More prominent card borders */
28+
.intro-card .sd-card {
29+
border: 2px solid var(--pst-color-border);
30+
overflow: hidden;
16831
}
169-
170-
.bd-toc-item.active > .bd-toc-link:hover {
171-
background-color: transparent;
32+
/* Shrink SVG icons */
33+
.intro-card .sd-card-img-top {
34+
margin: 1px;
35+
height: 100px;
36+
background-color: transparent !important;
17237
}
173-
174-
.bd-toc-item.active > .bd-sidenav {
175-
display: block;
38+
/* Color titles like links */
39+
.intro-card .sd-card-title {
40+
color: var(--pst-color-primary);
41+
font-size: var(--pst-font-size-h5);
17642
}
177-
178-
.bd-sidebar .nav > li > a {
179-
display: block;
180-
padding: 0.25rem 1.5rem;
181-
font-size: 90%;
182-
}
183-
184-
.bd-sidebar .nav > li > a:hover {
185-
text-decoration: none;
186-
background-color: transparent;
187-
}
188-
189-
.bd-sidebar .nav > .active > a,
190-
.bd-sidebar .nav > .active:hover > a {
191-
font-weight: 400;
192-
/* adjusted from original
193-
color: rgba(0, 0, 0, 0.85);
194-
background-color: transparent; */
195-
}
196-
197-
.bd-sidebar .nav > li > ul {
198-
list-style: none;
199-
padding: 0.25rem 1.5rem;
200-
}
201-
202-
.bd-sidebar .nav > li > ul > li > a {
203-
display: block;
204-
padding: 0.25rem 1.5rem;
205-
font-size: 90%;
206-
}
207-
208-
.bd-sidebar .nav > li > ul > .active > a,
209-
.bd-sidebar .nav > li > ul > .active:hover > a {
210-
font-weight: 400;
211-
}
212-
213-
dt:target {
214-
background-color: initial;
215-
}
216-
217-
/* Offsetting anchored elements within the main content to adjust for fixed header
218-
https://github.com/pandas-dev/pandas-sphinx-theme/issues/6 */
219-
main *:target::before {
220-
display: block;
221-
content: "";
222-
height: var(--navbar-height);
223-
margin-top: calc(-1 * var(--navbar-height));
224-
}
225-
226-
body {
227-
width: 100%;
228-
}
229-
230-
/* adjust toc font sizes to improve overview */
231-
.toc-h2 {
232-
font-size: 0.85rem;
233-
}
234-
235-
.toc-h3 {
236-
font-size: 0.75rem;
237-
}
238-
239-
.toc-h4 {
240-
font-size: 0.65rem;
241-
}
242-
243-
.toc-entry > .nav-link.active {
244-
font-weight: 400;
245-
color: #542437;
246-
background-color: transparent;
247-
border-left: 2px solid #563d7c;
248-
}
249-
250-
.nav-link:hover {
251-
border-style: none;
252-
}
253-
254-
/* Collapsing of the TOC sidebar while scrolling */
255-
256-
/* Nav: hide second level (shown on .active) */
257-
.bd-toc .nav .nav {
258-
display: none;
259-
}
260-
261-
.bd-toc .nav > .active > ul {
262-
display: block;
263-
}
264-
265-
/* Main index page overview cards */
266-
267-
.sd-card-img-top {
268-
width: 33% !important;
269-
display: block;
270-
margin-left: auto;
271-
margin-right: auto;
272-
margin-top: 10px;
43+
/* Don't have 'raised' color background for card interiors in dark mode */
44+
.bd-content .sd-card .sd-card-body {
45+
background-color: unset !important;
27346
}

‎doc/api.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1655,9 +1655,9 @@ Exceptions raised when manipulating trees.
16551655
.. autosummary::
16561656
:toctree: generated/
16571657

1658-
xarray.TreeIsomorphismError
1659-
xarray.InvalidTreeError
1660-
xarray.NotFoundInTreeError
1658+
TreeIsomorphismError
1659+
InvalidTreeError
1660+
NotFoundInTreeError
16611661

16621662
Advanced API
16631663
============

0 commit comments

Comments
 (0)