Skip to content

[Docs] Switch documentation theme to sphinx-book-theme #19828

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

Open
tlopex wants to merge 1 commit into
base: main
Choose a base branch
from
+107 −152
Open

[Docs] Switch documentation theme to sphinx-book-theme #19828

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ This folder contains the source of TVM's documentation, hosted at https://tvm.ap
```bash
# Pillow on Ubuntu may require libjpeg-dev from apt
./docker/bash.sh ci_gpu -c \
'python3 -m pip install --quiet tlcpack-sphinx-addon==0.2.1 && python3 -m pip freeze' > frozen-requirements.txt
'python3 -m pip install --quiet sphinx-book-theme==1.1.4 && python3 -m pip freeze' > frozen-requirements.txt

pip install -r frozen-requirements.txt
```
Expand Down
43 changes: 0 additions & 43 deletions docs/_static/css/tvm_theme.css
View file
Open in desktop

This file was deleted.

196 changes: 97 additions & 99 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,27 +348,112 @@ def jupyter_notebook(script_blocks, gallery_conf, target_dir, real_func):

# -- Options for HTML output ----------------------------------------------

# The theme is set by the make target
html_theme = os.environ.get("TVM_THEME", "rtd")
html_theme = "sphinx_book_theme"

on_rtd = os.environ.get("READTHEDOCS", None) == "True"
# only import rtd theme and set it if want to build docs locally
if not on_rtd and html_theme == "rtd":
html_theme = "sphinx_rtd_theme"
html_title = "Apache TVM"

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]

html_theme_options = {
"logo_only": True,
}

html_logo = "_static/img/tvm-logo-small.png"

html_favicon = "_static/img/tvm-logo-square.png"

# The Apache trademark/copyright footer is rendered through sphinx-book-theme's
# ``extra_footer`` hook (see footer_html below). This mirrors how the tvm-ffi docs
# (3rdparty/tvm-ffi/docs/conf.py) preserve the ASF menu under the book theme.
footer_dropdown = {
"name": "ASF",
"items": [
("Apache Homepage", "https://apache.org/"),
("License", "https://www.apache.org/licenses/"),
("Sponsorship", "https://www.apache.org/foundation/sponsorship.html"),
("Security", "https://tvm.apache.org/docs/reference/security.html"),
("Thanks", "https://www.apache.org/foundation/thanks.html"),
("Events", "https://www.apache.org/events/current-event"),
],
}

footer_links = [
("Community", "https://tvm.apache.org/community"),
("Download", "https://tvm.apache.org/download"),
("Docs", "https://tvm.apache.org/docs"),
]

footer_note = " ".join(
"""
Copyright © 2026 The Apache Software Foundation. Apache TVM, Apache, the Apache feather,
and the Apache TVM project logo are either trademarks or registered trademarks of
the Apache Software Foundation.""".split("\n")
).strip()


def footer_html() -> str:
"""Build the extra footer: nav links, ASF dropdown, and the Apache trademark note.

The copyright line is rendered natively by sphinx-book-theme (from the ``copyright``
config value), so it is intentionally not repeated here.
"""
dropdown_items = ""
for item_name, item_url in footer_dropdown["items"]:
dropdown_items += f'<li><a class="dropdown-item" href="{item_url}" target="_blank" style="font-size: 0.9em;">{item_name}</a></li>\n'

nav_links = " &middot; ".join(
f'<a href="{url}" style="color: #6c757d; text-decoration: none;">{name}</a>'
for name, url in footer_links
)

return f"""
<div class="footer-container" style="margin: 5px 0; font-size: 0.9em; color: #6c757d;">
<div class="footer-line1" style="display: flex; justify-content: center; align-items: center; gap: 0.9em; margin-bottom: 3px;">
<span class="footer-links">{nav_links}</span>
<div class="footer-dropdown">
<div class="dropdown">
<button class="btn btn-link dropdown-toggle" type="button" id="footerDropdown" data-bs-toggle="dropdown"
aria-expanded="false" style="font-size: 0.9em; color: #6c757d; text-decoration: none; padding: 0; border: none; background: none;">
{footer_dropdown["name"]}
</button>
<ul class="dropdown-menu" aria-labelledby="footerDropdown" style="font-size: 0.9em;">
{dropdown_items} </ul>
</div>
</div>
</div>
<div class="footer-line2" style="font-size: 0.9em; color: #6c757d; text-align: center;">
{footer_note}
</div>
</div>
"""


html_theme_options = {
"repository_url": "https://github.com/apache/tvm",
"repository_branch": "main",
"path_to_docs": "docs/",
"use_repository_button": True,
"use_edit_page_button": True,
"use_source_button": True,
"use_issues_button": True,
"show_toc_level": 2,
"show_navbar_depth": 1,
"icon_links": [
{
"name": "GitHub",
"url": "https://github.com/apache/tvm",
"icon": "fa-brands fa-github",
"type": "fontawesome",
},
{
"name": "TVM Homepage",
"url": "https://tvm.apache.org/",
"icon": "fa-solid fa-house",
"type": "fontawesome",
},
],
"extra_footer": footer_html(),
}


# Output file base name for HTML help builder.
htmlhelp_basename = project + "doc"
Expand Down Expand Up @@ -458,6 +543,8 @@ def force_gc(gallery_conf, fname):
"expected_failing_examples": [],
"reset_modules": ("matplotlib", "seaborn", force_gc, install_request_hook),
"promote_jupyter_magic": True,
# Drop the "Gallery generated by Sphinx-Gallery" signature line on generated pages.
"show_signature": False,
}

autodoc_default_options = {
Expand All @@ -471,95 +558,6 @@ def force_gc(gallery_conf, fname):
"tvm.tirx": ["tvm.ir", "tvm.runtime"],
}

## Setup header and other configs
import tlcpack_sphinx_addon

footer_copyright = "© 2026 Apache Software Foundation | All rights reserved"
footer_note = " ".join(
"""
Copyright © 2026 The Apache Software Foundation. Apache TVM, Apache, the Apache feather,
and the Apache TVM project logo are either trademarks or registered trademarks of
the Apache Software Foundation.""".split("\n")
).strip()

header_logo = "https://tvm.apache.org/assets/images/logo.svg"
header_logo_link = "https://tvm.apache.org/"

header_links = [
("Community", "https://tvm.apache.org/community"),
("Download", "https://tvm.apache.org/download"),
("Docs", "https://tvm.apache.org/docs"),
("GitHub", "https://github.com/apache/tvm/"),
]

header_dropdown = {
"name": "ASF",
"items": [
("Apache Homepage", "https://apache.org/"),
("License", "https://www.apache.org/licenses/"),
("Sponsorship", "https://www.apache.org/foundation/sponsorship.html"),
("Security", "https://tvm.apache.org/docs/reference/security.html"),
("Thanks", "https://www.apache.org/foundation/thanks.html"),
("Events", "https://www.apache.org/events/current-event"),
],
}


def fixup_tutorials(original_url: str) -> str:
if "docs/tutorial" in original_url:
# tutorials true source is in Python or .txt files, but Sphinx only sees
# the generated .rst files so this maps them back to the source
if original_url.endswith("index.rst"):
# for index pages, go to the README files
return re.sub(
r"docs/tutorial/(.*)index\.rst", "gallery/tutorial/\\1README.txt", original_url
)
else:
# otherwise for tutorials, redirect to python files
return re.sub(r"docs/tutorial/(.*)\.rst", "gallery/tutorial/\\1.py", original_url)
else:
# do nothing for normal non-tutorial .rst files
return original_url


html_context = {
"footer_copyright": footer_copyright,
"footer_note": footer_note,
"header_links": header_links,
"header_dropdown": header_dropdown,
"header_logo": header_logo,
"header_logo_link": header_logo_link,
"version_prefixes": [
"main",
"v0.8.0/",
"v0.9.0/",
"v0.10.0/",
"v0.11.0/",
"v0.12.0/",
"v0.13.0/",
"v0.14.0/",
"v0.15.0/",
"v0.16.0/",
"v0.17.0/",
"v0.18.0/",
"v0.19.0/",
"v0.20.0/",
"v0.21.0/",
"v0.22.0/",
"v0.23.0/",
],
"display_github": True,
"github_user": "apache",
"github_repo": "tvm",
"github_version": "main/docs/",
"theme_vcs_pageview_mode": "edit",
"edit_link_hook_fn": fixup_tutorials,
}

# add additional overrides
templates_path += [tlcpack_sphinx_addon.get_templates_path()]
html_static_path += [tlcpack_sphinx_addon.get_static_path()]


def update_alias_docstring(name, obj, lines):
"""Update the docstring of alias functions.
Expand Down
18 changes: 9 additions & 9 deletions tests/scripts/ci.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,17 +271,17 @@ def docs(
# These are taken from the ci-gpu image via pip freeze, consult that
# if there are any changes: https://github.com/apache/tvm/tree/main/docs#native
requirements = [
"Sphinx==4.2.0",
"tlcpack-sphinx-addon==0.2.1",
"Sphinx==8.1.3",
"sphinx_autodoc_annotation~=1.0",
"sphinx-gallery==0.20.0",
"sphinx-book-theme==1.1.4",
"pydata-sphinx-theme==0.15.4",
"autodocsumm==0.2.14",
"image==1.5.33",
# Temporary git link until a release is published
"git+https://github.com/sphinx-gallery/sphinx-gallery.git@6142f1791151849b5bec4bf3959f75697ba226cd",
"sphinx-rtd-theme==1.0.0",
"matplotlib==3.3.4",
"matplotlib==3.10.8",
"commonmark==0.9.1",
"Pillow==8.3.2",
"autodocsumm==0.2.7",
"docutils==0.16",
"docutils==0.21.2",
"Pillow==12.1.1",
]

extra_setup = [
Expand Down
Loading