Skip to content

Commit 068d819

Browse files
authored
Docs: draw the docs with the Vortex design system (#11207)
## Summary This draft PR changes the look of the docs to the Vortex design system that vortex.dev, bench, and the Explorer use. It is a prototype for review. It does not change the content or the URLs of any page. ## Changes - `docs/_theme/vortex/system/` holds copies of the system's CSS (tokens, docs, and focus). `vortex_theme.py` stops the build if a copy has a hand edit. - `layout.html` writes the system's header, navigation, "On this page" list, and footer. The pages need no JavaScript, except for search. - Code blocks use the system's syntax colours, with a label for each language. - The Pygments accessibility styles, `accessible-pygments`, and the Breathe hook are removed. - At 390 px, no page is wider than the screen. Today the API page and the index are wider. The build passes with warnings as errors. After gzip, each page gets 0.9 to 1.9 KB larger, and the CSS goes from 2.7 KB to 5.4 KB. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Will Manning <[email protected]>
1 parent a720e52 commit 068d819

12 files changed

Lines changed: 595 additions & 370 deletions

File tree

‎LICENSES/OFL-1.1.txt‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
2+
-----------------------------------------------------------
3+
4+
PREAMBLE
5+
The goals of the Open Font License (OFL) are to stimulate worldwide
6+
development of collaborative font projects, to support the font creation
7+
efforts of academic and linguistic communities, and to provide a free and
8+
open framework in which fonts may be shared and improved in partnership
9+
with others.
10+
11+
The OFL allows the licensed fonts to be used, studied, modified and
12+
redistributed freely as long as they are not sold by themselves. The
13+
fonts, including any derivative works, can be bundled, embedded,
14+
redistributed and/or sold with any software provided that any reserved
15+
names are not used by derivative works. The fonts and derivatives,
16+
however, cannot be released under any other type of license. The
17+
requirement for fonts to remain under this license does not apply
18+
to any document created using the fonts or their derivatives.
19+
20+
DEFINITIONS
21+
"Font Software" refers to the set of files released by the Copyright
22+
Holder(s) under this license and clearly marked as such. This may
23+
include source files, build scripts and documentation.
24+
25+
"Reserved Font Name" refers to any names specified as such after the
26+
copyright statement(s).
27+
28+
"Original Version" refers to the collection of Font Software components as
29+
distributed by the Copyright Holder(s).
30+
31+
"Modified Version" refers to any derivative made by adding to, deleting,
32+
or substituting -- in part or in whole -- any of the components of the
33+
Original Version, by changing formats or by porting the Font Software to a
34+
new environment.
35+
36+
"Author" refers to any designer, engineer, programmer, technical
37+
writer or other person who contributed to the Font Software.
38+
39+
PERMISSION & CONDITIONS
40+
Permission is hereby granted, free of charge, to any person obtaining
41+
a copy of the Font Software, to use, study, copy, merge, embed, modify,
42+
redistribute, and sell modified and unmodified copies of the Font
43+
Software, subject to the following conditions:
44+
45+
1) Neither the Font Software nor any of its individual components,
46+
in Original or Modified Versions, may be sold by itself.
47+
48+
2) Original or Modified Versions of the Font Software may be bundled,
49+
redistributed and/or sold with any software, provided that each copy
50+
contains the above copyright notice and this license. These can be
51+
included either as stand-alone text files, human-readable headers or
52+
in the appropriate machine-readable metadata fields within text or
53+
binary files as long as those fields can be easily viewed by the user.
54+
55+
3) No Modified Version of the Font Software may use the Reserved Font
56+
Name(s) unless explicit written permission is granted by the corresponding
57+
Copyright Holder. This restriction only applies to the primary font name as
58+
presented to the users.
59+
60+
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
61+
Software shall not be used to promote, endorse or advertise any
62+
Modified Version, except to acknowledge the contribution(s) of the
63+
Copyright Holder(s) and the Author(s) or with their explicit written
64+
permission.
65+
66+
5) The Font Software, modified or unmodified, in part or in whole,
67+
must be distributed entirely under this license, and must not be
68+
distributed under any other license. The requirement for fonts to
69+
remain under this license does not apply to any document created
70+
using the Font Software.
71+
72+
TERMINATION
73+
This license becomes null and void if any of the above conditions are
74+
not met.
75+
76+
DISCLAIMER
77+
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
78+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
79+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
80+
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
81+
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
82+
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
83+
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
84+
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
85+
OTHER DEALINGS IN THE FONT SOFTWARE.

‎REUSE.toml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,21 @@ path = "docs/**"
66
SPDX-FileCopyrightText = "Copyright the Vortex contributors"
77
SPDX-License-Identifier = "CC-BY-4.0"
88

9+
# The docs theme's copies of the Vortex design system's CSS are code, under Apache-2.0.
10+
[[annotations]]
11+
path = "docs/_theme/vortex/system/**"
12+
precedence = "override"
13+
SPDX-FileCopyrightText = "Copyright the Vortex contributors"
14+
SPDX-License-Identifier = "Apache-2.0"
15+
16+
# The docs theme's Geist Mono is Google Fonts' Latin subset of the font, under the SIL Open Font
17+
# License.
18+
[[annotations]]
19+
path = "docs/_static/fonts/geist-mono-latin.woff2"
20+
precedence = "override"
21+
SPDX-FileCopyrightText = "2024 The Geist Project Authors (https://github.com/vercel/geist-font.git)"
22+
SPDX-License-Identifier = "OFL-1.1"
23+
924
# BtrBlocks diagram is licensed under CC-BY-4.0.
1025
[[annotations]]
1126
path = "vortex-btrblocks/decision-tree.*"

‎docs/_ext/vortex_theme.py‎

Lines changed: 36 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,34 @@
11
"""
22
Build hooks for our theme.
3-
1. Add pygment styles to vortex.css
3+
1. Join the Vortex design system's tokens and docs rules with the theme's own CSS into one vortex.css,
4+
and fail the build if a copy of the system was edited by hand
45
2. Load only one CSS and no JS per page except search page
56
3. Rewrite TOC into detail/summary with regex so it loads without JS
67
4. Minify CSS
78
"""
89

910
from __future__ import annotations
1011

12+
import hashlib
1113
import re
1214
from pathlib import Path
1315
from typing import TYPE_CHECKING
1416

1517
import rcssmin
16-
from pygments.formatters.html import HtmlFormatter
18+
from sphinx.errors import ExtensionError
1719

1820
if TYPE_CHECKING:
1921
from typing import Any
2022

2123
from sphinx.application import Sphinx
2224

23-
_LIGHT_STYLE = "a11y-high-contrast-light"
24-
_DARK_STYLE = "a11y-high-contrast-dark"
25-
2625
_DOCS_DIR = Path(__file__).parent.parent
27-
_CSS_SOURCE = _DOCS_DIR / "_theme" / "vortex" / "vortex.css"
26+
_THEME_DIR = _DOCS_DIR / "_theme" / "vortex"
27+
# Copies of the design system, written by its tools/site-styles.mjs. Each starts with a header
28+
# whose sha256 covers the rest of the file.
29+
_SYSTEM_CSS = (_THEME_DIR / "system" / "vortex-tokens.css", _THEME_DIR / "system" / "vortex.css")
30+
_CSS_SOURCE = _THEME_DIR / "vortex.css"
31+
_SYSTEM_HEADER = re.compile(r"\A/\*.*?sha256 ([0-9a-f]{64}) \*/\n", re.S)
2832
_GEN_STATIC = _DOCS_DIR / "_build" / "_gen_static"
2933

3034
_PAGE_CSS = {"_static/vortex.css"}
@@ -36,12 +40,19 @@
3640
}
3741

3842

43+
def _system_css(path: Path) -> str:
44+
text = path.read_text()
45+
header = _SYSTEM_HEADER.match(text)
46+
body = text[header.end() :] if header else ""
47+
if not header or hashlib.sha256(body.encode()).hexdigest() != header.group(1):
48+
raise ExtensionError(f"{path} does not match its sha256 header: edit the design system and copy it again")
49+
return body
50+
51+
3952
def _css(app: Sphinx) -> None:
4053
if app.builder.format != "html":
4154
return
42-
light = HtmlFormatter(style=_LIGHT_STYLE).get_style_defs(".highlight")
43-
dark = HtmlFormatter(style=_DARK_STYLE).get_style_defs(".highlight")
44-
css = rcssmin.cssmin(f"{_CSS_SOURCE.read_text()}\n{light}\n@media (prefers-color-scheme: dark) {{\n{dark}\n}}\n")
55+
css = rcssmin.cssmin("\n".join([*map(_system_css, _SYSTEM_CSS), _CSS_SOURCE.read_text()]))
4556
out = _GEN_STATIC / "vortex.css"
4657
if not out.exists() or out.read_text() != css:
4758
out.write_text(css)
@@ -57,22 +68,34 @@ def _filter_assets(app: Sphinx, pagename: str, templatename: str, context: dict[
5768
]
5869

5970

60-
_SUMMARY = '<summary aria-label="Toggle section"></summary>'
61-
_TOC_BRANCH = re.compile(r"</a>\s*<ul([^>]*)>")
71+
_TOC_BRANCH = re.compile(r">((?:(?!</a>).)*)</a>\s*<ul([^>]*)>", re.S)
6272
_TOC_BRANCH_END = re.compile(r"</ul>\s*</li>")
63-
_TOC_CURRENT_BRANCH = re.compile(rf"<details>({re.escape(_SUMMARY)}<ul[^>]*\bcurrent\b)")
73+
_TOC_CURRENT_BRANCH = re.compile(r"<details>(<summary[^>]*></summary><ul[^>]*\bcurrent\b)")
6474
_TOC_CURRENT_PARENT = re.compile(r'(<a aria-current="page" (?:(?!</a>).)*</a>)<details>', re.S)
6575
_TOC_CURRENT_LINK = re.compile(r'<a class="([^"]*\bcurrent\b[^"]*)"')
76+
_TAGS = re.compile(r"<[^>]+>")
77+
# The page's own contents: one entry for the page title, holding the sections. The rail shows the
78+
# sections alone, since the title is already the page's h1.
79+
_PAGE_TOC = re.compile(r'\s*<ul>\s*<li><a [^>]*href="#">(?:(?!</a>).)*</a>(<ul>.*</ul>)\s*</li>\s*</ul>\s*', re.S)
80+
81+
82+
def _branch(m: re.Match[str]) -> str:
83+
# Each toggle is named after its section, so a screen reader can tell them apart.
84+
label = _TAGS.sub("", m.group(1)).strip()
85+
return f'>{m.group(1)}</a><details><summary aria-label="{label} pages"></summary><ul{m.group(2)}>'
6686

6787

6888
def _toc(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: object) -> None:
89+
page_toc = _PAGE_TOC.fullmatch(context.get("toc") or "")
90+
if page_toc:
91+
context["toc"] = page_toc.group(1)
6992
toctree = context.get("toctree")
7093
if toctree is None:
7194
context["vortex_globaltoc"] = ""
7295
return
7396
html = toctree(maxdepth=3, collapse=False, includehidden=True, titles_only=True) or ""
7497
html = _TOC_CURRENT_LINK.sub(r'<a aria-current="page" class="\1"', html)
75-
html = _TOC_BRANCH.sub(rf"</a><details>{_SUMMARY}<ul\1>", html)
98+
html = _TOC_BRANCH.sub(_branch, html)
7699
html = _TOC_CURRENT_BRANCH.sub(r"<details open>\1", html)
77100
html = _TOC_CURRENT_PARENT.sub(r"\1<details open>", html)
78101
html = _TOC_BRANCH_END.sub("</ul></details></li>", html)
22.6 KB
Binary file not shown.

‎docs/_theme/vortex/layout.html‎

Lines changed: 64 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,20 @@
44
{%- else %}
55
{%- set titlesuffix = "" %}
66
{%- endif %}
7-
<html lang="{{ language }}" data-content_root="{{ content_root }}">
7+
{%- set github = "https://github.com/vortex-data/vortex" %}
8+
<html lang="{{ language }}" data-content_root="{{ content_root }}" data-theme="system">
89
<head>
910
<meta charset="{{ encoding }}" />
10-
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
1111
{{- metatags }}
12+
{%- if 'name="viewport"' not in metatags %}
13+
<meta name="viewport" content="width=device-width, initial-scale=1" />
14+
{%- endif %}
1215
{%- block htmltitle %}
1316
<title>{{ title|striptags|e }}{{ titlesuffix }}</title>
1417
{%- endblock %}
18+
{%- if meta and meta.description %}
19+
<meta name="description" content="{{ meta.description|e }}" />
20+
{%- endif %}
1521
<meta property="og:title" content="{{ title|striptags|e }}" />
1622
<meta property="og:type" content="website" />
1723
<meta property="og:site_name" content="{{ project|e }}" />
@@ -22,6 +28,7 @@
2228
{%- for css in css_files %}
2329
{{ css_tag(css) }}
2430
{%- endfor %}
31+
<link rel="preload" href="{{ pathto('_static/fonts/geist-mono-latin.woff2', 1) }}" as="font" type="font/woff2" crossorigin />
2532
{%- block scripts %}
2633
{%- for js in script_files %}
2734
{{ js_tag(js) }}
@@ -41,49 +48,76 @@
4148
{%- endif %}
4249
{%- block extrahead %}{% endblock %}
4350
</head>
44-
<body class="page-{{ pagename|replace('/', '-')|e }}">
45-
<a class="skip-link" href="#main">{{ _('Skip to content') }}</a>
46-
<input type="checkbox" id="nav-toggle" class="visually-hidden" />
47-
<header class="header">
48-
<label for="nav-toggle" class="nav-toggle" aria-label="{{ _('Toggle navigation') }}">
49-
<svg viewBox="0 0 16 16" width="20" height="20" aria-hidden="true"><path stroke="currentColor" stroke-width="1.5" d="M1 3.5h14M1 8h14M1 12.5h14"/></svg>
51+
<body class="vx-docs page-{{ pagename|replace('/', '-')|e }}">
52+
<a class="vx-docs-skip" href="#main">{{ _('Skip to content') }}</a>
53+
<input type="checkbox" id="nav-toggle" class="vx-docs-toggle" aria-label="{{ _('Show the site navigation') }}" />
54+
<header class="vx-docs-header">
55+
<label for="nav-toggle" class="vx-docs-menu" aria-hidden="true">
56+
<svg viewBox="0 -960 960 960"><path d="M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z"/></svg>
5057
</label>
51-
<a class="logo" href="{{ pathto(root_doc)|e }}">
52-
<img class="only-light" src="{{ pathto('_static/vortex_logo.svg', 1) }}" alt="" width="24" height="24" />
53-
<img class="only-dark" src="{{ pathto('_static/vortex_logo_dark_theme.svg', 1) }}" alt="" width="24" height="24" />
54-
<span>Vortex</span>
58+
<a class="vx-docs-brand" href="{{ pathto(root_doc)|e }}">
59+
<picture>
60+
<source srcset="{{ pathto('_static/vortex_wordmark.svg', 1) }}" media="(prefers-color-scheme: light)" />
61+
<img src="{{ pathto('_static/vortex_wordmark_dark_theme.svg', 1) }}" alt="Vortex" width="83" height="24" />
62+
</picture>
63+
<span class="vx-docs-label">{{ _('Docs') }}</span>
5564
</a>
56-
<form class="search" role="search" action="{{ pathto('search') }}" method="get">
57-
<input type="search" name="q" placeholder="{{ _('Search') }}" aria-label="{{ _('Search the docs') }}" />
65+
<form class="vx-docs-search" role="search" action="{{ pathto('search') }}" method="get">
66+
<svg viewBox="0 -960 960 960" aria-hidden="true"><path d="M784-120 532-372q-30 24-69 38t-83 14q-109 0-184.5-75.5T120-580q0-109 75.5-184.5T380-840q109 0 184.5 75.5T640-580q0 44-14 83t-38 69l252 252-56 56ZM380-400q75 0 127.5-52.5T560-580q0-75-52.5-127.5T380-760q-75 0-127.5 52.5T200-580q0 75 52.5 127.5T380-400Z"/></svg>
67+
<input type="search" name="q" placeholder="{{ _('Search the docs') }}" aria-label="{{ _('Search the docs') }}" />
5868
</form>
59-
<nav class="extlinks" aria-label="{{ _('External links') }}">
60-
<a href="https://github.com/vortex-data/vortex">GitHub</a>
61-
<a href="https://pypi.org/project/vortex-data">PyPI</a>
62-
<a href="https://crates.io/crates/vortex">crates.io</a>
69+
<nav class="vx-docs-links" aria-label="{{ _('Project links') }}">
70+
<a class="is-narrow" href="{{ pathto('search') }}" aria-label="{{ _('Search the docs') }}"><svg viewBox="0 -960 960 960" aria-hidden="true"><path d="M784-120 532-372q-30 24-69 38t-83 14q-109 0-184.5-75.5T120-580q0-109 75.5-184.5T380-840q109 0 184.5 75.5T640-580q0 44-14 83t-38 69l252 252-56 56ZM380-400q75 0 127.5-52.5T560-580q0-75-52.5-127.5T380-760q-75 0-127.5 52.5T200-580q0 75 52.5 127.5T380-400Z"/></svg></a>
71+
<a href="{{ github }}">GitHub</a>
72+
<a class="is-wide" href="https://pypi.org/project/vortex-data">PyPI</a>
73+
<a class="is-wide" href="https://crates.io/crates/vortex">crates.io</a>
6374
</nav>
6475
</header>
65-
<div class="layout">
66-
<nav class="sidebar" id="nav" aria-label="{{ _('Site navigation') }}">
76+
<div class="vx-docs-layout">
77+
<nav class="vx-docs-nav" id="nav" aria-label="{{ _('Site navigation') }}">
6778
{{ vortex_globaltoc }}
6879
</nav>
69-
<main id="main" class="content" role="main">
70-
{%- block body %}{% endblock %}
71-
<footer class="footer">
72-
{%- if page_source_suffix %}
73-
<a href="https://github.com/vortex-data/vortex/edit/develop/docs/{{ pagename }}{{ page_source_suffix }}">{{ _('Edit this page') }}</a> ·
80+
<div class="vx-docs-page">
81+
{%- if display_toc %}
82+
<details class="vx-docs-fold">
83+
<summary>{{ _('On this page') }}</summary>
84+
{{ toc }}
85+
</details>
86+
{%- endif %}
87+
<main id="main" class="vx-docs-main" role="main">
88+
{%- block body %}{% endblock %}
89+
</main>
90+
{%- if page_source_suffix %}
91+
<p class="vx-docs-edit"><a href="{{ github }}/edit/develop/docs/{{ pagename }}{{ page_source_suffix }}">{{ _('Edit this page') }}</a></p>
92+
{%- endif %}
93+
{%- if prev or next %}
94+
<nav class="vx-docs-pager" aria-label="{{ _('Previous and next') }}">
95+
{%- if prev %}
96+
<a href="{{ prev.link|e }}"><span class="vx-docs-label">{{ _('Previous') }}</span>{{ prev.title }}</a>
7497
{%- endif %}
75-
© {{ copyright|e }}.
76-
{%- if show_sphinx %} {% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}{% endif %}
77-
</footer>
78-
</main>
98+
{%- if next %}
99+
<a class="is-next" href="{{ next.link|e }}"><span class="vx-docs-label">{{ _('Next') }}</span>{{ next.title }}</a>
100+
{%- endif %}
101+
</nav>
102+
{%- endif %}
103+
</div>
79104
{%- if display_toc %}
80-
<aside class="pagetoc">
105+
<aside class="vx-docs-toc">
81106
<nav aria-label="{{ _('On this page') }}">
82107
<p>{{ _('On this page') }}</p>
83108
{{ toc }}
84109
</nav>
85110
</aside>
86111
{%- endif %}
87112
</div>
113+
<footer class="vx-docs-footer">
114+
<p>Copyright © Vortex a Series of LF Projects, LLC. For web site terms of use, trademark policy and other project policies please see <a href="https://lfprojects.org/policies">lfprojects.org/policies</a>.</p>
115+
<nav aria-label="{{ _('Project') }}">
116+
<a href="https://vortex.dev/charter.pdf">{{ _('Charter') }}</a>
117+
<a href="https://lfprojects.org/policies/code-of-conduct/">{{ _('Code of conduct') }}</a>
118+
<a href="{{ github }}/blob/develop/SECURITY.md">{{ _('Security') }}</a>
119+
<a href="https://zoom-lfx.platform.linuxfoundation.org/meetings/vortex">{{ _('Calendar') }}</a>
120+
</nav>
121+
</footer>
88122
</body>
89123
</html>

0 commit comments

Comments
 (0)