Skip to content

Commit f2915f2

Browse files
tfcollinstfcollins
committed
doc: switch Sphinx theme to cosmic (adi-doctools) to match pyadi-iio
Replace the furo theme with the cosmic theme provided by adi-doctools, matching pyadi-iio and the rest of the ADI doc fleet. - requirements_doc.txt: drop furo/sphinx-favicon, add adi-doctools tarball, bump sphinx>=5.0 - conf.py: html_theme=cosmic, add adi_doctools extension and needs_extensions floor, set html_favicon directly, trim theme options to light/dark logos, drop furo-only DEV_BUILD announcement - style.css: drop furo sidebar/data-theme rules, keep index-logo background fix - index.md: use cosmic .only-light/.only-dark image classes for the index-page logo
1 parent 852f5cd commit f2915f2

4 files changed

Lines changed: 17 additions & 145 deletions

File tree

‎CI/doc/requirements_doc.txt‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
1-
sphinx>=2.0
1+
sphinx>=5.0
22
myst-parser
3-
furo
4-
sphinx-favicon
3+
https://github.com/analogdevicesinc/doctools/releases/download/latest/adi-doctools.tar.gz
54
sphinxcontrib-mermaid
65
sphinx-simplepdf
76
pillow
87
numpy
98
jinja2
10-
sphinx_design
9+
sphinx_design

‎CI/doc/source/_static/css/style.css‎

Lines changed: 6 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,7 @@
1-
:root {
2-
/* Defaults */
3-
--display-dark-stuff: none;
4-
--display-light-stuff: block;
5-
--sidebar-highligh-color-hover: black;
6-
--sidebar-highligh-color: white;
7-
--display-dark-stuff: none;
8-
--display-light-stuff: block;
9-
}
10-
11-
@media (prefers-color-scheme: dark) {
12-
:root {
13-
/* Change to dark if user prefers dark */
14-
--display-dark-stuff: block;
15-
--display-light-stuff: none;
16-
--sidebar-highligh-color-hover: white;
17-
--sidebar-highligh-color: black;
18-
--display-dark-stuff: block;
19-
--display-light-stuff: none;
20-
}
21-
}
22-
23-
24-
[data-theme=light] {
25-
--sidebar-highligh-color-hover: black;
26-
--sidebar-highligh-color: white;
27-
--display-dark-stuff: none;
28-
--display-light-stuff: block;
29-
}
30-
31-
[data-theme=dark] {
32-
--sidebar-highligh-color-hover: white;
33-
--sidebar-highligh-color: black;
34-
--display-dark-stuff: block;
35-
--display-light-stuff: none;
36-
}
37-
38-
/* Pad sidebar entries so radius does not touch content or browser*/
39-
body>div>aside>div>div>div.sidebar-scroll>div>ul {
40-
padding-right: 10px;
41-
padding-left: 10px;
42-
}
43-
44-
/* Disable sidebar title */
45-
.sidebar-brand-text {
46-
display: none;
47-
}
48-
49-
/* Add better highlighting on selected sidebar entry */
50-
.sidebar-tree .current>.reference {
51-
border-radius: 25px;
52-
color: var(--sidebar-highligh-color);
53-
padding-bottom: 5px;
54-
padding-top: 5px;
55-
}
56-
57-
/* Add better highlighting on selected second level sidebar entry */
58-
.toctree-l2 .current.reference.internal {
59-
border-radius: 25px;
60-
color: var(--sidebar-highligh-color);
61-
padding-bottom: 1px;
62-
padding-top: 1px;
63-
margin: 2px;
64-
}
65-
66-
/* Add better highlighting on selected hovered sidebar entry */
67-
.sidebar-tree .current>.reference:hover {
68-
color: var(--sidebar-highligh-color-hover);
69-
border: 1px solid var(--sidebar-highligh-color-hover);
70-
padding-bottom: 4px;
71-
padding-top: 4px;
72-
}
73-
74-
/* Add better highlighting on selected second level hovered sidebar entry */
75-
.toctree-l2 .current.reference.internal:hover {
76-
color: var(--sidebar-highligh-color-hover);
77-
border: 1px solid var(--sidebar-highligh-color-hover);
78-
padding-bottom: 1px;
79-
padding-top: 1px;
80-
margin: 2px;
81-
}
82-
83-
84-
/* Hide/display logo on index page based on theme */
85-
#indexlogo_light {
86-
display: var(--display-dark-stuff);
87-
}
88-
89-
#indexlogo_dark {
90-
display: var(--display-light-stuff);
91-
}
92-
93-
element.style {
94-
display: none;
1+
/* Remove the theme background behind the large index-page logo so that the
2+
transparent PNG does not get a colored box drawn behind it. The light/dark
3+
index logos are selected by the cosmic theme's .only-light / .only-dark
4+
classes (see index.md). */
5+
#indexlogo img {
6+
background: none;
957
}

‎CI/doc/source/conf.py‎

Lines changed: 5 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@
1010
# add these directories to sys.path here. If the directory is relative to the
1111
# documentation root, use os.path.abspath to make it absolute, like shown here.
1212
#
13-
import contextlib
1413
import os
1514
import shutil
1615
import sys
@@ -63,13 +62,15 @@
6362
"sphinx.ext.coverage",
6463
"sphinx.ext.githubpages",
6564
"myst_parser",
66-
"sphinx_favicon",
6765
"sphinxcontrib.mermaid",
6866
# "sphinx_copybutton",
6967
# "sphinx_togglebutton", # Using this?
7068
"sphinx_design",
69+
"adi_doctools",
7170
]
7271

72+
needs_extensions = {"adi_doctools": "0.4.21"}
73+
7374
myst_enable_extensions = [
7475
"colon_fence",
7576
]
@@ -90,10 +91,10 @@
9091
# The theme to use for HTML and HTML Help pages. See the documentation for
9192
# a list of builtin themes.
9293
#
93-
html_theme = "furo"
94+
html_theme = "cosmic"
9495

9596
html_title = f"{project} {release}"
96-
#favicons = ["favicon.png"]
97+
html_favicon = os.path.join("_static", "favicon.png")
9798

9899
# Add any paths that contain custom static files (such as style sheets) here,
99100
# relative to this directory. They are copied after the builtin static files,
@@ -107,40 +108,4 @@
107108
html_theme_options = {
108109
"light_logo": os.path.join("logos", "logo_black_cropped.png"),
109110
"dark_logo": os.path.join("logos", "logo_white_cropped.png"),
110-
"dark_css_variables": {
111-
"color-sidebar-item-background--current": "white",
112-
"color-sidebar-link-text": "white",
113-
"color-sidebar-link-text--top-level": "white",
114-
},
115-
"light_css_variables": {
116-
"color-sidebar-item-background--current": "black",
117-
"color-sidebar-link-text": "black",
118-
"color-sidebar-link-text--top-level": "black",
119-
},
120111
}
121-
122-
if os.getenv("DEV_BUILD"):
123-
branch = os.getenv("GIT_BRANCH")
124-
if branch is None:
125-
with contextlib.suppress(Exception):
126-
# Try to get branch from git
127-
import subprocess
128-
129-
branch = (
130-
subprocess.run(
131-
args=["git", "rev-parse", "--abbrev-ref", "HEAD"],
132-
capture_output=True,
133-
)
134-
.stdout.decode("utf-8")
135-
.strip()
136-
)
137-
if branch is None:
138-
branch = "_UNKNOWN_" # type: ignore
139-
html_theme_options["announcement"] = (
140-
"<em>WARNING: This is a development \
141-
build of branch: <b>"
142-
+ branch
143-
+ "</b>. Please use the latest stable release.</em>"
144-
)
145-
html_theme_options["dark_css_variables"]["color-announcement-text"] = "red"
146-
html_theme_options["light_css_variables"]["color-announcement-text"] = "red"

‎CI/doc/source/index.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,9 @@
88

99
<br>
1010
<center>
11-
<div style="width:70%;">
12-
<div id="indexlogo_dark">
13-
<img src="_static/logos/logo_black.png" alt="PyADI-IIO Logo" />
14-
</div>
15-
<div id="indexlogo_light">
16-
<img src="_static/logos/logo_white.png" alt="PyADI-IIO Logo" />
17-
</div>
11+
<div id="indexlogo" style="width:70%;">
12+
<img class="only-light" src="_static/logos/logo_black.png" alt="Transceiver Toolbox Logo" />
13+
<img class="only-dark" src="_static/logos/logo_white.png" alt="Transceiver Toolbox Logo" />
1814
</div>
1915
</center>
2016

0 commit comments

Comments
 (0)