Skip to content

Commit eab1539

Browse files
authored
Docs improvements (rapidsai#2993)
Resolves rapidsai#2992. 1. Change the sphinx theme to `nvidia_sphinx_theme` just like cuvs. This theme has better function signature formatting for the API reference. 2. Keep the rapids branding for the favicon and top left corner logo 3. Add higher quality rapids branding images 4. Copy NVIDIA/cuvs#1377 overload grouping from cuvs. # Old <img width="1512" height="766" alt="old_docs" src="https://github.com/user-attachments/assets/cdf05a5b-d219-4831-9669-2718b3be7da5" /> # New <img width="1433" height="882" alt="new_docs" src="https://github.com/user-attachments/assets/aca1224e-88b6-4c8f-8b03-ab8b89ec29eb" /> Authors: - Anupam (https://github.com/aamijar) Approvers: - Micka (https://github.com/lowener) - Bradley Dice (https://github.com/bdice) URL: rapidsai#2993
1 parent cb6243b commit eab1539

12 files changed

Lines changed: 152 additions & 27 deletions

conda/environments/all_cuda-129_arch-aarch64.yaml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ channels:
55
- rapidsai
66
- conda-forge
77
dependencies:
8-
- breathe
8+
- breathe>=4.35.0
99
- c-compiler
1010
- clang-tools=20.1.8
1111
- clang==20.1.8
@@ -34,7 +34,6 @@ dependencies:
3434
- numpy>=1.23,<3.0
3535
- numpydoc
3636
- pre-commit
37-
- pydata-sphinx-theme
3837
- pylibraft==26.6.*,>=0.0.0a0
3938
- pytest
4039
- pytest-cov
@@ -46,8 +45,10 @@ dependencies:
4645
- scikit-build-core>=0.11.0
4746
- scikit-learn
4847
- scipy
49-
- sphinx
5048
- sphinx-copybutton
5149
- sphinx-markdown-tables
50+
- sphinx>=8.0.0
5251
- sysroot_linux-aarch64==2.28
52+
- pip:
53+
- nvidia-sphinx-theme
5354
name: all_cuda-129_arch-aarch64

conda/environments/all_cuda-129_arch-x86_64.yaml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ channels:
55
- rapidsai
66
- conda-forge
77
dependencies:
8-
- breathe
8+
- breathe>=4.35.0
99
- c-compiler
1010
- clang-tools=20.1.8
1111
- clang==20.1.8
@@ -34,7 +34,6 @@ dependencies:
3434
- numpy>=1.23,<3.0
3535
- numpydoc
3636
- pre-commit
37-
- pydata-sphinx-theme
3837
- pylibraft==26.6.*,>=0.0.0a0
3938
- pytest
4039
- pytest-cov
@@ -46,8 +45,10 @@ dependencies:
4645
- scikit-build-core>=0.11.0
4746
- scikit-learn
4847
- scipy
49-
- sphinx
5048
- sphinx-copybutton
5149
- sphinx-markdown-tables
50+
- sphinx>=8.0.0
5251
- sysroot_linux-64==2.28
52+
- pip:
53+
- nvidia-sphinx-theme
5354
name: all_cuda-129_arch-x86_64

conda/environments/all_cuda-131_arch-aarch64.yaml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ channels:
55
- rapidsai
66
- conda-forge
77
dependencies:
8-
- breathe
8+
- breathe>=4.35.0
99
- c-compiler
1010
- clang-tools=20.1.8
1111
- clang==20.1.8
@@ -34,7 +34,6 @@ dependencies:
3434
- numpy>=1.23,<3.0
3535
- numpydoc
3636
- pre-commit
37-
- pydata-sphinx-theme
3837
- pylibraft==26.6.*,>=0.0.0a0
3938
- pytest
4039
- pytest-cov
@@ -46,8 +45,10 @@ dependencies:
4645
- scikit-build-core>=0.11.0
4746
- scikit-learn
4847
- scipy
49-
- sphinx
5048
- sphinx-copybutton
5149
- sphinx-markdown-tables
50+
- sphinx>=8.0.0
5251
- sysroot_linux-aarch64==2.28
52+
- pip:
53+
- nvidia-sphinx-theme
5354
name: all_cuda-131_arch-aarch64

conda/environments/all_cuda-131_arch-x86_64.yaml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ channels:
55
- rapidsai
66
- conda-forge
77
dependencies:
8-
- breathe
8+
- breathe>=4.35.0
99
- c-compiler
1010
- clang-tools=20.1.8
1111
- clang==20.1.8
@@ -34,7 +34,6 @@ dependencies:
3434
- numpy>=1.23,<3.0
3535
- numpydoc
3636
- pre-commit
37-
- pydata-sphinx-theme
3837
- pylibraft==26.6.*,>=0.0.0a0
3938
- pytest
4039
- pytest-cov
@@ -46,8 +45,10 @@ dependencies:
4645
- scikit-build-core>=0.11.0
4746
- scikit-learn
4847
- scipy
49-
- sphinx
5048
- sphinx-copybutton
5149
- sphinx-markdown-tables
50+
- sphinx>=8.0.0
5251
- sysroot_linux-64==2.28
52+
- pip:
53+
- nvidia-sphinx-theme
5354
name: all_cuda-131_arch-x86_64

dependencies.yaml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -382,16 +382,17 @@ dependencies:
382382
common:
383383
- output_types: [conda]
384384
packages:
385-
- breathe
385+
- breathe>=4.35.0
386386
- doxygen>=1.8.20
387387
- graphviz
388388
- ipython
389389
- numpydoc
390-
- pydata-sphinx-theme
391390
- recommonmark
391+
- sphinx>=8.0.0
392392
- sphinx-copybutton
393393
- sphinx-markdown-tables
394-
- sphinx
394+
- pip:
395+
- nvidia-sphinx-theme
395396
py_version:
396397
specific:
397398
- output_types: conda
Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
document.addEventListener("DOMContentLoaded", () => {
2+
const toc = document.querySelector("#pst-page-toc-nav") ||
3+
document.querySelector(".bd-toc-nav");
4+
if (!toc) return;
5+
6+
// Get all TOC links
7+
const links = toc.querySelectorAll("a");
8+
9+
const seen = new Set();
10+
links.forEach(link => {
11+
let text = link.textContent.trim();
12+
let norm = text.replace(/\(\)$/, ""); // strip trailing ()
13+
14+
if (seen.has(norm)) {
15+
// hide duplicate
16+
link.parentElement.style.display = "none";
17+
} else {
18+
seen.add(norm);
19+
}
20+
});
21+
});
22+
23+
document.addEventListener("DOMContentLoaded", () => {
24+
const toc = document.querySelector(".toctree-wrapper");
25+
if (!toc) return;
26+
27+
const leaf_traversal_fn = (leaf) => {
28+
try {
29+
const links = leaf.querySelectorAll("a");
30+
if (!links) return;
31+
const seen = new Set();
32+
links.forEach(link => {
33+
let text = link.textContent.trim();
34+
let norm = text.replace(/\(\)$/, ""); // strip trailing ()
35+
36+
if (seen.has(norm)) {
37+
// hide duplicate
38+
link.parentElement.style.display = "none";
39+
} else {
40+
seen.add(norm);
41+
}
42+
});
43+
} catch (error) {
44+
console.error(error);
45+
}
46+
};
47+
queue = [toc.querySelector("li")];
48+
while (queue.length > 0) {
49+
const tree = queue.shift();
50+
try {
51+
if (tree.childElementCount > 1 &&
52+
tree.firstChild.hasAttribute("href") &&
53+
tree.firstChild.attributes["href"].value.includes("#")) {
54+
leaf_traversal_fn(tree.childNodes[1]);
55+
} else {
56+
const child = tree.querySelector("li");
57+
if (child) {
58+
queue.push(child);
59+
}
60+
}
61+
} catch (error) {
62+
console.error(error);
63+
}
64+
if (tree.nextElementSibling) {
65+
queue.push(tree.nextElementSibling);
66+
}
67+
}
68+
});

docs/source/_static/references.css

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,15 @@
11

2+
/* Constrain navbar logo size and add spacing */
3+
.navbar-brand.logo .logo__image {
4+
height: 32px !important;
5+
width: auto !important;
6+
margin-right: 0.75rem;
7+
}
8+
9+
.navbar-brand.logo {
10+
padding: 0.5rem 0;
11+
}
12+
213
/* Fix references to not look like parameters */
314
dl.citation > dt.label {
415
display: unset !important;
@@ -21,8 +32,3 @@ dl.citation > dt.label > span::before {
2132
dl.citation > dt.label > span::after {
2233
content: "]";
2334
}
24-
25-
/* Make navbar logo smaller */
26-
.logo__image {
27-
height: 32px !important;
28-
}
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<a class="navbar-brand logo" href="{{ pathto(root_doc) }}">
2+
<img src="{{ logo_url }}" class="logo__image" alt="{{ docstitle }} - Home"/>
3+
<p class="title logo__title">{{ docstitle }}</p>
4+
</a>

docs/source/conf.py

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# SPDX-FileCopyrightText: Copyright (c) 2018-2026, NVIDIA CORPORATION.
22
# SPDX-License-Identifier: Apache-2.0
33

4+
import datetime
45
import os
56
import sys
67
from packaging.version import Version
@@ -63,8 +64,8 @@
6364
master_doc = "index"
6465

6566
# General information about the project.
66-
project = "raft"
67-
copyright = "2023-2026, NVIDIA Corporation"
67+
project = "RAFT"
68+
copyright = f"2023-{datetime.datetime.today().year}, NVIDIA Corporation"
6869
author = "NVIDIA Corporation"
6970

7071
# The version info for the project you're documenting, acts as replacement for
@@ -103,18 +104,16 @@
103104
# a list of builtin themes.
104105
#
105106

106-
html_theme = "pydata_sphinx_theme"
107-
html_logo = "../../img/rapids_logo.png"
107+
html_theme = "nvidia_sphinx_theme"
108+
html_logo = "../../img/logo-purple-bg-white-text.svg"
109+
html_favicon = "../../img/icon-512x512.png"
108110

109111

110112
# Theme options are theme-specific and customize the look and feel of a theme
111113
# further. For a list of options available for each theme, see the
112114
# documentation.
113115
#
114116
html_theme_options = {
115-
"logo": {
116-
"text": "RAFT",
117-
},
118117
"external_links": [],
119118
# https://github.com/pydata/pydata-sphinx-theme/issues/1220
120119
"icon_links": [],
@@ -206,6 +205,7 @@ def setup(app):
206205
app.add_js_file(
207206
"https://docs.rapids.ai/assets/js/custom.js", loading_method="defer"
208207
)
208+
app.add_js_file("collapse_overloads.js")
209209

210210

211211
# The following is used by sphinx.ext.linkcode to provide links to github

img/icon-512x512.png

14.7 KB
Loading

0 commit comments

Comments
 (0)