diff --git a/changelog.d/ITL-1170.md b/changelog.d/ITL-1170.md index 7561fba45..207edf24d 100644 --- a/changelog.d/ITL-1170.md +++ b/changelog.d/ITL-1170.md @@ -10,3 +10,9 @@ `DOCS_SITE_BASE` (base path), from the environment or, in CI, the repository variables of the same names; unset or empty, it is `https://metamorphic-labs.github.io/orcapod-python/`. (ITL-1170) +- The documentation site takes the look of [orcapod.org](https://orcapod.org): the + Orcapod logo in the header and as the favicon, the Asap and Lexend Exa fonts (bundled + with the site), orcapod.org's background and text colours, and a blue accent for links, the + sidebar, the banner and notes, in light and dark mode. The home page opens with the + logo, a tagline and buttons to Getting Started, the tutorial and the repository. + (ITL-1170) diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/README.md b/docs/dev/specs/2026-11-17-docs-site-theme/README.md new file mode 100644 index 000000000..96a68a45f --- /dev/null +++ b/docs/dev/specs/2026-11-17-docs-site-theme/README.md @@ -0,0 +1,71 @@ +# The documentation site's theme (ITL-1170) + +Developer request, November 17, 2026: the documentation site follows orcapod.org for the +official logo, the fonts and the colour scheme, with a bluer theme. The theme itself is +`site/src/styles/orcapod.css`; `site/README.md` ("The theme") describes it. + +## What orcapod.org uses + +- Logo: `images/iconOutlined.png` (986 x 894, black on transparent, white details) in its + navigation and `images/orcapodlogofull.png` (icon and wordmark) on its home page; the + favicon is `favicon.ico` (48 x 48 and 32 x 32). It has no SVG and no dark variant. +- Fonts (SIL Open Font License 1.1): Asap for the text, Lexend Exa bold for the name + ("orcapod", lower case) in the navigation, Asap Condensed in the footer. +- Colours: background `#fcfafc`, text `#0a0a0a`, navigation and footer bars `#0a0a0a` + with white text. There is no brand blue and no dark mode. + +## The site's theme + +The site takes `iconOutlined.png` (header logo, inverted in dark mode) and `favicon.ico` +unmodified, the background and text colours, the name in lower case, and the fonts Asap +and Lexend Exa (bold), bundled from the `@fontsource-variable/asap` and +`@fontsource/lexend-exa` packages (OFL-1.1, allowed for the site by the developer on +November 17, 2026) and served by the site itself. The blue accent +family (hue about 212) is the site's own. + +The home page has a hero (developer request, November 17, 2026): Starlight's `splash` +template with the logo, the name, the tagline "A Python library for building highly +reproducible scientific data pipelines." (the first sentence of `docs/index.md`, +shortened) and three buttons, Get started, Tutorial and GitHub. Choices: + +- `splash`, as Starlight's own landing pages: the home page has no sidebar and no table + of contents; at phone width it has no menu button, and the buttons, the search and + the page's "Next steps" lead on. +- The image is `iconOutlined.png`, the header's logo, inverted in dark mode as there, and + the title beside it is the name in Lexend Exa bold, lower case: together they read as + orcapod.org's full logo. The full logo (`orcapodlogofull.png`, 3001 x 3001, 203 KB) + would repeat the name under the title, and Astro resizes images only with `sharp`, + which the site does not install (libvips is LGPL-3.0-or-later), so it would be served + at full size. Astro's passthrough service writes the hero's copy of the 80 KB icon at + a URL of its own, so the home page loads it twice (160 KB). +- `docs/index.md` is unchanged: `scripts/docs_site_content.py` writes the hero into the + generated page's front matter (`HOME_HERO`), and resolves its buttons like any link. + +| | Light | Dark | +|---|---|---| +| Background | `#fcfafc` | `#0b0f16` | +| Body text | `#2b3440` | `#c8d0da` | +| Strongest text | `#0a0a0a` | `#ffffff` | +| Links (`--sl-color-text-accent`) | `#1565c0` | `#a8d0ff` | +| Accent low / accent / accent high | `#d6e6fa` / `#1565c0` / `#0b3d73` | `#10294a` / `#3d8fe8` / `#a8d0ff` | + +WCAG contrast ratios (AA asks 4.5:1 for body text): light body text 12.1:1, links 5.5:1 +on the background and 4.9:1 on the inline-code background, banner text 5.5:1; dark body +text 12.3:1, links 12.0:1 on the background and 9.4:1 on the inline-code background, +banner text 9.1:1. + +## Screenshots + +Taken from a local `pnpm build`, served statically, with headless Chrome at 1280 x 900 +(colour scheme set through the DevTools protocol, after `document.fonts.ready`), scaled to +960 x 675. They show the bundled brand fonts. + +- `home-light.png`, `home-dark.png`: the home page before the hero: header, banner, + sidebar, a code block. +- `home-hero-light.png`, `home-hero-dark.png`: the home page with the hero, 1280 wide; + `home-hero-phone-light.png`, `home-hero-phone-dark.png`: at 390 x 844 (a phone). +- `concept-function-pods-light.png`, `concept-function-pods-dark.png`: code, a caution and + a note aside. +- `in-development-notice-light.png`, `in-development-notice-dark.png`: the "In + development" notice. +- `api-operators-light.png`, `api-operators-dark.png`: the generated API reference. diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/api-operators-dark.png b/docs/dev/specs/2026-11-17-docs-site-theme/api-operators-dark.png new file mode 100644 index 000000000..8a4df8acd Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/api-operators-dark.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/api-operators-light.png b/docs/dev/specs/2026-11-17-docs-site-theme/api-operators-light.png new file mode 100644 index 000000000..36fe149fc Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/api-operators-light.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/concept-function-pods-dark.png b/docs/dev/specs/2026-11-17-docs-site-theme/concept-function-pods-dark.png new file mode 100644 index 000000000..6cbc5137f Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/concept-function-pods-dark.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/concept-function-pods-light.png b/docs/dev/specs/2026-11-17-docs-site-theme/concept-function-pods-light.png new file mode 100644 index 000000000..8ca12a40f Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/concept-function-pods-light.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/home-dark.png b/docs/dev/specs/2026-11-17-docs-site-theme/home-dark.png new file mode 100644 index 000000000..29a0ad945 Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/home-dark.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-dark.png b/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-dark.png new file mode 100644 index 000000000..3deea328a Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-dark.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-light.png b/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-light.png new file mode 100644 index 000000000..2dbd3314e Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-light.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-phone-dark.png b/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-phone-dark.png new file mode 100644 index 000000000..95224c925 Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-phone-dark.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-phone-light.png b/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-phone-light.png new file mode 100644 index 000000000..b088b6227 Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/home-hero-phone-light.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/home-light.png b/docs/dev/specs/2026-11-17-docs-site-theme/home-light.png new file mode 100644 index 000000000..183ed2704 Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/home-light.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/in-development-notice-dark.png b/docs/dev/specs/2026-11-17-docs-site-theme/in-development-notice-dark.png new file mode 100644 index 000000000..55c58d92a Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/in-development-notice-dark.png differ diff --git a/docs/dev/specs/2026-11-17-docs-site-theme/in-development-notice-light.png b/docs/dev/specs/2026-11-17-docs-site-theme/in-development-notice-light.png new file mode 100644 index 000000000..8c405ba48 Binary files /dev/null and b/docs/dev/specs/2026-11-17-docs-site-theme/in-development-notice-light.png differ diff --git a/scripts/check_site_licenses.py b/scripts/check_site_licenses.py index 984f7e26c..771a315a9 100644 --- a/scripts/check_site_licenses.py +++ b/scripts/check_site_licenses.py @@ -3,7 +3,8 @@ The Python dependencies are checked by ``.github/workflows/_license-check.yml`` (``pip-licenses``). The site under ``site/`` is built with npm packages; this script checks them against the same allow list, plus the permissive licenses only npm packages -use (``BlueOak-1.0.0``, ``CC0-1.0``). +use (``BlueOak-1.0.0``, ``CC0-1.0``) and the font license of the site's bundled fonts +(``OFL-1.1``). Usage (the ``docs-site`` workflow runs it): @@ -18,8 +19,8 @@ import sys from typing import cast -# The license identifiers allowed, as in _license-check.yml, plus BlueOak-1.0.0 and -# CC0-1.0. +# The license identifiers allowed, as in _license-check.yml, plus BlueOak-1.0.0, +# CC0-1.0 and OFL-1.1. ALLOWED = frozenset( { "MIT", @@ -34,6 +35,10 @@ "Unlicense", "BlueOak-1.0.0", "CC0-1.0", + # SIL Open Font License 1.1 (OSI-approved): the brand fonts (Asap, Lexend Exa) + # bundled with the documentation site only, never with the Python package. + # Approved by the developer, November 17, 2026 (ITL-1170). + "OFL-1.1", } ) diff --git a/scripts/docs_site_content.py b/scripts/docs_site_content.py index 1e6b175fb..c0e083fe5 100644 --- a/scripts/docs_site_content.py +++ b/scripts/docs_site_content.py @@ -4,7 +4,8 @@ pages as they are. The Starlight site under ``site/`` never holds a copy in git. This script writes the site's content collection (``site/src/content/docs/``) and its static files (``site/public/``) from ``docs/`` on every build; both are generated and -ignored by git. +ignored by git. ``site/public/`` also gets the site's own static files +(``SITE_PUBLIC_FILES``: the favicon). The conversion is mechanical and deterministic. For each published page: @@ -18,6 +19,11 @@ ``docs/`` (``workshop_data.py``) copies the file to the site's static files. - The ```` markers of the sample tests are removed. +The home page (``docs/index.md``) also gets the site's hero (``HOME_HERO``): Starlight's +``splash`` template with the logo, a tagline and buttons, written as its front matter. +``docs/index.md`` itself stays a plain Markdown page. The hero's links are resolved like +the page's own, so a button to a page that is not published fails the build. + A link to a page or file that does not exist, or to a page that is not published, is an error: the build fails, as ``mkdocs build --strict`` did. The API pages (``docs/api/*.md``) are converted the same way, after ``docs_site_api.py`` has replaced @@ -74,6 +80,11 @@ # is an error, so that publishing a new folder (or not) is a decision. EXCLUDED = ("dev",) +# The site's own static files, written into ``site/public/`` with the files the pages +# link to: published path to source file. The favicon is orcapod.org's (``favicon`` in +# ``site/astro.config.mjs``). +SITE_PUBLIC_FILES = {"favicon.ico": SITE_DIR / "src" / "assets" / "favicon.ico"} + # mkdocs admonition types and the Starlight aside each becomes. ASIDE_TYPES = { "note": "note", @@ -185,6 +196,62 @@ class Page: text: str +@dataclass(frozen=True) +class HeroAction: + """A button of the home page's hero. + + Attributes: + text: The button's label. + target: A page, as a link from the home page (``getting-started.md``), or an + external URL. + variant: Starlight's button style: ``primary``, ``secondary`` or ``minimal``. + icon: The name of a Starlight icon shown beside the label, if any. + """ + + text: str + target: str + variant: str + icon: str | None = None + + +@dataclass(frozen=True) +class Hero: + """The home page's hero (Starlight's ``hero`` front matter, ``splash`` template). + + The title is the page's title. + + Attributes: + tagline: The line below the title. + image: The image shown beside the title (a file under ``site/src/assets``). + actions: The buttons, in order. + """ + + tagline: str + image: Path + actions: tuple[HeroAction, ...] + + +# The home page and its hero. The image is the header's logo (orcapod.org's +# iconOutlined.png), so the browser loads it once; the title beside it is the name, which +# the theme sets as orcapod.org's wordmark (Lexend Exa, lower case). The tagline is the +# first sentence of docs/index.md, shortened. +HOME_PAGE = "index.md" +HOME_HERO = Hero( + tagline="A Python library for building highly reproducible scientific data pipelines.", + image=SITE_DIR / "src" / "assets" / "orcapod-icon.png", + actions=( + HeroAction("Get started", "getting-started.md", "primary", "right-arrow"), + HeroAction("Tutorial", "tutorial/index.md", "secondary"), + HeroAction( + "GitHub", + "https://github.com/metamorphic-labs/orcapod-python", + "minimal", + "github", + ), + ), +) + + class SiteSettingsError(Exception): """The site's origin or base path is not one the site can be built for.""" @@ -534,9 +601,58 @@ def resolve(self, page: str, target: str) -> str: return self._base.rstrip("/") + "/" + resolved + sep + fragment -def convert_page(page: Page, resolver: LinkResolver) -> str: +def hero_front_matter( + hero: Hero, resolver: LinkResolver, page_dir: Path +) -> dict[str, object]: + """Return the front matter that gives the home page ``hero``. + + Args: + hero: The hero. + resolver: Resolves the buttons' targets, as links from the home page. + page_dir: The directory the home page is written to; the image path is relative + to it, as Starlight requires. + + Raises: + ContentError: If a button's target is not a published page, or the image does + not exist. + """ + if not hero.image.is_file(): + raise ContentError(f"the hero image {hero.image} does not exist") + actions: list[dict[str, str]] = [] + for action in hero.actions: + entry = { + "text": action.text, + "link": resolver.resolve(HOME_PAGE, action.target), + "variant": action.variant, + } + if action.icon is not None: + entry["icon"] = action.icon + actions.append(entry) + image = Path(os.path.relpath(hero.image, page_dir)).as_posix() + return { + "template": "splash", + "hero": { + "tagline": hero.tagline, + # Decorative: the title beside it names the project. + "image": {"file": image, "alt": ""}, + "actions": actions, + }, + } + + +def convert_page( + page: Page, + resolver: LinkResolver, + front_matter: Mapping[str, object] | None = None, +) -> str: """Return the Starlight form of ``page``. + Args: + page: The page. + resolver: Resolves the page's links. + front_matter: Front matter written after the title (each value as JSON, which + YAML reads as it is). + Raises: ContentError: If the page cannot be converted. """ @@ -550,36 +666,66 @@ def convert_page(page: Page, resolver: LinkResolver) -> str: line, lambda target: resolver.resolve(page.path, target) ), ) - front_matter = ["---", f"title: {json.dumps(title, ensure_ascii=False)}", "---", ""] - return "\n".join(front_matter + lines).rstrip("\n") + "\n" + header = ["---", f"title: {json.dumps(title, ensure_ascii=False)}"] + header += [ + f"{key}: {json.dumps(value, ensure_ascii=False)}" + for key, value in (front_matter or {}).items() + ] + return "\n".join([*header, "---", "", *lines]).rstrip("\n") + "\n" def build_content( - pages: Sequence[Page], docs_dir: Path, out_dir: Path, public_dir: Path, base: str + pages: Sequence[Page], + docs_dir: Path, + out_dir: Path, + public_dir: Path, + base: str, + site_files: Mapping[str, bytes] | None = None, + hero: Hero | None = None, ) -> None: """Write the converted ``pages`` to ``out_dir`` and linked files to ``public_dir``. Each directory ends up holding exactly what this build writes, so a page removed from ``docs/`` leaves the site. + Args: + pages: The published pages. + docs_dir: The ``docs/`` folder the pages and linked files come from. + out_dir: The site's content collection. + public_dir: The site's static files. + base: The site's base path. + site_files: The site's own static files (published path to content), written + into ``public_dir`` beside the linked files. + hero: The home page's hero, if it has one. + Raises: - ContentError: If a page cannot be converted; its path is in the message. + ContentError: If a page cannot be converted (its path is in the message), or + ``hero`` is given and there is no home page. """ converted: dict[str, str] = {} try: resolver = LinkResolver(docs_dir, pages, base) except ContentError as exc: raise ContentError(f"a page has no title: {exc}") from exc + if hero is not None and HOME_PAGE not in {page.path for page in pages}: + raise ContentError(f"the hero needs a home page, docs/{HOME_PAGE}") for page in pages: try: - converted[page.path] = convert_page(page, resolver) + front_matter = ( + hero_front_matter(hero, resolver, out_dir.resolve()) + if hero is not None and page.path == HOME_PAGE + else None + ) + converted[page.path] = convert_page(page, resolver, front_matter) except ContentError as exc: raise ContentError(f"docs/{page.path}: {exc}") from exc _sync_tree(out_dir, {path: text.encode() for path, text in converted.items()}) - _sync_tree( - public_dir, - {asset: (docs_dir / asset).read_bytes() for asset in sorted(resolver.assets)}, - ) + # A linked file is never at the top level (a top-level entry of docs/ is a page or + # a folder), where the site's own files are. + public = { + asset: (docs_dir / asset).read_bytes() for asset in sorted(resolver.assets) + } + _sync_tree(public_dir, {**public, **(site_files or {})}) def _sync_tree(directory: Path, files: dict[str, bytes]) -> None: @@ -615,6 +761,11 @@ def main(argv: Sequence[str] | None = None) -> int: _ = parser.add_argument( "--base", default="/", help="the site's base path (normalize_site_base)" ) + _ = parser.add_argument( + "--no-hero", + action="store_true", + help="build the home page as a plain page, without the site's hero", + ) _ = parser.add_argument( "--site-settings", action="store_true", @@ -658,7 +809,11 @@ def main(argv: Sequence[str] | None = None) -> int: except ApiPageError as exc: raise ContentError(f"docs/{path}: {exc}") from exc pages.append(Page(path, text)) - build_content(pages, docs_dir, out_dir, public_dir, base) + site_files = { + path: source.read_bytes() for path, source in SITE_PUBLIC_FILES.items() + } + hero = None if cast(bool, args.no_hero) else HOME_HERO + build_content(pages, docs_dir, out_dir, public_dir, base, site_files, hero) except ContentError as exc: print(f"error: {exc}", file=sys.stderr) return 1 diff --git a/site/README.md b/site/README.md index 0ad7c3c99..4f1f5bb5c 100644 --- a/site/README.md +++ b/site/README.md @@ -93,12 +93,44 @@ site's links use the new address. ## What is committed `package.json`, `pnpm-lock.yaml` (exact versions), `pnpm-workspace.yaml`, -`astro.config.mjs` (site settings, sidebar), `src/content.config.ts`, -`src/routeData.ts` (the banner every page shows) and this file. `node_modules/`, `dist/`, `.astro/`, `src/content/docs/` and `public/` are +`astro.config.mjs` (site settings, sidebar, logo, favicon), `src/content.config.ts`, +`src/routeData.ts` (the banner every page shows), `src/styles/orcapod.css` (the theme), +`src/assets/` (the logo and the favicon) and this file. `node_modules/`, `dist/`, `.astro/`, `src/content/docs/` and `public/` are generated. Astro's optional image optimizer, `sharp`, is not installed (`pnpm-workspace.yaml`): the -site has no images, and its `libvips` is under a license the project does not allow. +site's one image, the logo, is served as it is, and `libvips` is under a license the +project does not allow. + +## The theme + +The site follows [orcapod.org](https://orcapod.org), the project's home page, with a blue +accent of its own: + +- the logo (`src/assets/orcapod-icon.png`) and the favicon (`src/assets/favicon.ico`) + are orcapod.org's files, unmodified. The logo is black on a transparent background; + in dark mode it is shown inverted. The content build writes the favicon into + `public/` (`SITE_PUBLIC_FILES` in `../scripts/docs_site_content.py`); +- the text is set in Asap and the site's name in Lexend Exa (bold, lower case), the + fonts of orcapod.org, with the system fonts after them. Both are bundled with the site + (`@fontsource-variable/asap`, `@fontsource/lexend-exa` weight 700; the `customCss` + entries in `astro.config.mjs`) and served from it, never from a font host. They are + under the SIL Open Font License 1.1, which `../scripts/check_site_licenses.py` allows + (developer, November 17, 2026); +- the light theme has orcapod.org's background (`#fcfafc`) and text (`#0a0a0a`), the + dark theme a near-black with a blue tint; links, the current sidebar entry, the + banner and note asides are blue (`#1565c0` light, `#3d8fe8` and `#a8d0ff` dark). + Every text colour meets WCAG AA against its background. + +The home page opens with a hero (Starlight's `splash` template, so it has no sidebar): +the logo, the name in Lexend Exa, a tagline and three buttons (Get started, Tutorial, +GitHub). `docs/index.md` stays a plain page; the content build adds the hero as its front +matter (`HOME_HERO` in `../scripts/docs_site_content.py`), and its buttons are links +checked like any other. The hero's logo is the header's file: Astro could only resize +orcapod.org's 3001 x 3001 full logo with `sharp`, which the site does not install. + +`src/styles/orcapod.css` holds the colours and fonts (Starlight's `--sl-color-*` and +`--sl-font` variables). ## CI and publishing diff --git a/site/astro.config.mjs b/site/astro.config.mjs index d9bc8fbd0..61cbb70e9 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -83,6 +83,18 @@ export default defineConfig({ title: 'Orcapod', description: 'Intuitive and powerful library for highly reproducible scientific data pipelines', + // orcapod.org's logo and favicon, unmodified (src/assets). The content build + // writes the favicon into public/ (SITE_PUBLIC_FILES in docs_site_content.py). + logo: { src: './src/assets/orcapod-icon.png' }, + favicon: '/favicon.ico', + // The brand fonts, bundled with the site (OFL-1.1; served from the site itself, + // never from a font host): Asap for the text, Lexend Exa bold for the name. + // Then the colour scheme (src/styles/orcapod.css). + customCss: [ + '@fontsource-variable/asap', + '@fontsource/lexend-exa/700.css', + './src/styles/orcapod.css', + ], plugins: [starlightLinksValidator()], // The banner on every page: the site documents main, not a release. routeMiddleware: './src/routeData.ts', diff --git a/site/package.json b/site/package.json index 175028d86..1223e9b5e 100644 --- a/site/package.json +++ b/site/package.json @@ -15,6 +15,8 @@ "dependencies": { "@astrojs/markdown-remark": "7.3.9", "@astrojs/starlight": "0.43.1", + "@fontsource-variable/asap": "5.3.0", + "@fontsource/lexend-exa": "5.3.0", "astro": "7.4.12", "starlight-links-validator": "0.27.0" } diff --git a/site/pnpm-lock.yaml b/site/pnpm-lock.yaml index 0824136da..bc0c94ec3 100644 --- a/site/pnpm-lock.yaml +++ b/site/pnpm-lock.yaml @@ -184,6 +184,12 @@ importers: '@astrojs/starlight': specifier: 0.43.1 version: 0.43.1(@astrojs/markdown-remark@7.3.9(supports-color@10.2.2))(astro@7.4.12(@astrojs/markdown-remark@7.3.9(supports-color@10.2.2))(@types/node@26.6.6)(yaml@2.9.1))(supports-color@10.2.2) + '@fontsource-variable/asap': + specifier: 5.3.0 + version: 5.3.0 + '@fontsource/lexend-exa': + specifier: 5.3.0 + version: 5.3.0 astro: specifier: 7.4.12 version: 7.4.12(@astrojs/markdown-remark@7.3.9(supports-color@10.2.2))(@types/node@26.6.6)(yaml@2.9.1) @@ -492,6 +498,12 @@ packages: '@expressive-code/plugin-text-markers@0.44.3': resolution: {integrity: sha512-4Ae2xRSDV5kdWPsi40xWbOtoihbzM0zLVjQKkDAnD5KzFXl+6/kd+VhuWOlTRVaJ5cqGk++vCbAaf0MR1XbZlw==} + '@fontsource-variable/asap@5.3.0': + resolution: {integrity: sha512-muKYZYKww2t16U8T83yo/wcFU+yxdY5kPaCxx0ZVlfRAyI7YMPmoUGVHOZIfe5FIrNM97ZwAi6eo18Kz1Z3mNQ==} + + '@fontsource/lexend-exa@5.3.0': + resolution: {integrity: sha512-CW48kdNUQvU8yLXxFvjMtF6C0fGpsk7jefAKhIJJD3kao9r8qv9XpnNbBUvf53BoAAzcvSewdkSBSuGuLOimhw==} + '@jridgewell/sourcemap-codec@1.6.0': resolution: {integrity: sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==} @@ -2274,6 +2286,10 @@ snapshots: dependencies: '@expressive-code/core': 0.44.3 + '@fontsource-variable/asap@5.3.0': {} + + '@fontsource/lexend-exa@5.3.0': {} + '@jridgewell/sourcemap-codec@1.6.0': {} '@mdx-js/mdx@3.1.1(supports-color@10.2.2)': diff --git a/site/pnpm-workspace.yaml b/site/pnpm-workspace.yaml index effdc849c..6e15bb2ba 100644 --- a/site/pnpm-workspace.yaml +++ b/site/pnpm-workspace.yaml @@ -1,4 +1,5 @@ # Astro's optional image optimizer (sharp, with libvips under LGPL-3.0-or-later) is not -# installed: the site has no images to optimize and uses Astro's passthrough image service. +# installed: the site's one image (the logo) is served as it is, by Astro's passthrough +# image service. overrides: sharp: '-' diff --git a/site/src/assets/favicon.ico b/site/src/assets/favicon.ico new file mode 100644 index 000000000..4d363d664 Binary files /dev/null and b/site/src/assets/favicon.ico differ diff --git a/site/src/assets/orcapod-icon.png b/site/src/assets/orcapod-icon.png new file mode 100644 index 000000000..ba2c40f34 Binary files /dev/null and b/site/src/assets/orcapod-icon.png differ diff --git a/site/src/styles/orcapod.css b/site/src/styles/orcapod.css new file mode 100644 index 000000000..f6df9b9d8 --- /dev/null +++ b/site/src/styles/orcapod.css @@ -0,0 +1,88 @@ +/* + * The Orcapod theme for Starlight: the brand of orcapod.org (its logo, fonts, background + * and text colours) with a blue accent family. + * + * orcapod.org is black on #fcfafc; it has no brand blue. The blues here (hue about 212) + * are the site's own: links, the current sidebar entry, the development-version banner + * and note asides. Every text colour meets WCAG AA against the background it sits on + * (body text over 12:1, links 4.9:1 or more in light mode and 9.4:1 or more in dark). + * + * Starlight's dark theme is the default (:root); the light theme overrides it + * (:root[data-theme='light']), as in Starlight's own props.css. + */ + +:root { + /* Fonts: orcapod.org sets its text in Asap and its name in Lexend Exa. Both are bundled + * with the site (@fontsource-variable/asap, @fontsource/lexend-exa 700; customCss in + * astro.config.mjs); Starlight appends its system font stack after them. */ + --sl-font: 'Asap Variable', 'Asap'; + --orcapod-font-title: 'Lexend Exa'; + + /* Dark: near-black with a blue tint (orcapod.org's bars are #0a0a0a). */ + --sl-color-white: #ffffff; + --sl-color-gray-1: #e7ecf2; + --sl-color-gray-2: #c8d0da; + --sl-color-gray-3: #8a96a6; + --sl-color-gray-4: #4f5b6b; + --sl-color-gray-5: #1d2735; + --sl-color-gray-6: #121925; + --sl-color-black: #0b0f16; + + --sl-color-accent-low: #10294a; + --sl-color-accent: #3d8fe8; + --sl-color-accent-high: #a8d0ff; + + --sl-color-blue-low: #10294a; + --sl-color-blue: #3d8fe8; + --sl-color-blue-high: #a8d0ff; +} + +:root[data-theme='light'] { + /* Light: orcapod.org's background (#fcfafc) and text (#0a0a0a). */ + --sl-color-white: #0a0a0a; + --sl-color-gray-1: #1b2129; + --sl-color-gray-2: #2b3440; + --sl-color-gray-3: #4a5563; + --sl-color-gray-4: #7d8898; + --sl-color-gray-5: #c3cbd6; + --sl-color-gray-6: #e8eef5; + --sl-color-gray-7: #f3f6fa; + --sl-color-black: #fcfafc; + + --sl-color-accent-low: #d6e6fa; + --sl-color-accent: #1565c0; + --sl-color-accent-high: #0b3d73; + + --sl-color-blue-low: #d6e6fa; + --sl-color-blue: #1565c0; + --sl-color-blue-high: #0b3d73; +} + +/* The site's name beside the logo, as orcapod.org's navigation writes it: lower case, + * Lexend Exa bold, in the text colour (black, white in dark mode) rather than the + * accent. The page titles keep "Orcapod". */ +.site-title { + color: var(--sl-color-white); + font-family: var(--orcapod-font-title), var(--__sl-font); + font-weight: 700; + text-transform: lowercase; +} + +/* The logo is black on a transparent background. In dark mode it is shown inverted + * (white orcas, dark eyes); the file is orcapod.org's, unmodified. */ +:root:not([data-theme='light']) .site-title img { + filter: invert(1); +} + +/* The home page's hero (HOME_HERO in scripts/docs_site_content.py): the title is the name, + * set as orcapod.org's wordmark (Lexend Exa bold, lower case); the logo is the header's, + * inverted in dark mode in the same way. */ +.hero h1 { + font-family: var(--orcapod-font-title), var(--__sl-font); + font-weight: 700; + text-transform: lowercase; +} + +:root:not([data-theme='light']) .hero > img { + filter: invert(1); +} diff --git a/tests/test_docs/test_site_content.py b/tests/test_docs/test_site_content.py index 1561c650f..dde9dcfc5 100644 --- a/tests/test_docs/test_site_content.py +++ b/tests/test_docs/test_site_content.py @@ -27,8 +27,9 @@ def run_build( - docs: Path, tmp_path: Path, base: str = "/" + docs: Path, tmp_path: Path, base: str = "/", hero: bool = False ) -> tuple[subprocess.CompletedProcess[str], Path, Path]: + """Run the content build; without ``hero``, the home page is built as a plain page.""" out = tmp_path / "out" public = tmp_path / "public" proc = subprocess.run( @@ -43,6 +44,7 @@ def run_build( str(public), "--base", base, + *([] if hero else ["--no-hero"]), ], capture_output=True, text=True, @@ -69,12 +71,21 @@ def build_ok(tmp_path: Path, pages: dict[str, str], base: str = "/") -> Path: return out -def build_fails(tmp_path: Path, pages: dict[str, str]) -> str: - proc, _, _ = run_build(make_docs(tmp_path, pages), tmp_path) +def build_fails(tmp_path: Path, pages: dict[str, str], hero: bool = False) -> str: + proc, _, _ = run_build(make_docs(tmp_path, pages), tmp_path, hero=hero) assert proc.returncode != 0, "the build should have failed" return proc.stderr +def front_matter(text: str) -> dict[str, object]: + """The front matter of a generated page: each line ``key: ``.""" + lines = text.split("---\n")[1].splitlines() + return { + key: json.loads(value) + for key, _, value in (line.partition(": ") for line in lines) + } + + # --------------------------------------------------------------------------- # The real documentation # --------------------------------------------------------------------------- @@ -82,9 +93,11 @@ def build_fails(tmp_path: Path, pages: dict[str, str]) -> str: def test_the_documentation_builds(tmp_path: Path): """Every page converts, every link resolves, every API object and docstring renders.""" - proc, out, public = run_build(REPO_ROOT / "docs", tmp_path, "/orcapod-python/") + proc, out, public = run_build( + REPO_ROOT / "docs", tmp_path, "/orcapod-python/", hero=True + ) assert proc.returncode == 0, proc.stderr - assert (out / "index.md").is_file() + assert front_matter((out / "index.md").read_text())["template"] == "splash" assert (out / "api" / "operators.md").is_file() assert (public / "tutorial" / "workshop_data.py").is_file() assert not (out / "dev").exists() @@ -94,8 +107,8 @@ def test_the_documentation_builds(tmp_path: Path): def test_the_build_is_deterministic(tmp_path: Path): - first, out_a, _ = run_build(REPO_ROOT / "docs", tmp_path / "a") - second, out_b, _ = run_build(REPO_ROOT / "docs", tmp_path / "b") + first, out_a, _ = run_build(REPO_ROOT / "docs", tmp_path / "a", hero=True) + second, out_b, _ = run_build(REPO_ROOT / "docs", tmp_path / "b", hero=True) assert first.returncode == 0 and second.returncode == 0 files_a = sorted(p.relative_to(out_a) for p in out_a.rglob("*.md")) files_b = sorted(p.relative_to(out_b) for p in out_b.rglob("*.md")) @@ -120,6 +133,81 @@ def test_a_page_without_a_title_fails(tmp_path: Path): assert "title" in build_fails(tmp_path, {"index.md": "Body.\n"}) +# --------------------------------------------------------------------------- +# The home page's hero +# --------------------------------------------------------------------------- + +HERO_PAGES = { + "index.md": "# Orcapod\n\nBody.\n", + "getting-started.md": "# Getting Started\n", + "tutorial/index.md": "# Tutorial\n", +} + + +def test_the_home_page_gets_the_hero(tmp_path: Path): + """Splash template, the header's logo, buttons that resolve under the base.""" + docs = make_docs(tmp_path, HERO_PAGES) + proc, out, _ = run_build(docs, tmp_path, "/orcapod-python/", hero=True) + assert proc.returncode == 0, proc.stderr + home = (out / "index.md").read_text() + assert home.endswith("---\n\nBody.\n") + meta = front_matter(home) + assert meta["title"] == "Orcapod" + assert meta["template"] == "splash" + hero = cast(dict[str, object], meta["hero"]) + tagline = ( + "A Python library for building highly reproducible scientific data pipelines." + ) + assert hero["tagline"] == tagline + image = cast(dict[str, str], hero["image"]) + assert image["alt"] == "" + logo = REPO_ROOT / "site" / "src" / "assets" / "orcapod-icon.png" + assert (out / image["file"]).resolve() == logo + assert hero["actions"] == [ + { + "text": "Get started", + "link": "/orcapod-python/getting-started/", + "variant": "primary", + "icon": "right-arrow", + }, + { + "text": "Tutorial", + "link": "/orcapod-python/tutorial/", + "variant": "secondary", + }, + { + "text": "GitHub", + "link": "https://github.com/metamorphic-labs/orcapod-python", + "variant": "minimal", + "icon": "github", + }, + ] + # Only the home page has it. + assert "hero" not in front_matter((out / "getting-started.md").read_text()) + + +def test_the_tagline_is_the_home_page_s_own_wording(): + """The tagline shortens the first sentence of docs/index.md; it claims nothing new.""" + home = (REPO_ROOT / "docs" / "index.md").read_text(encoding="utf-8") + first = " ".join(home.split()) + assert ( + "Python library for building highly reproducible scientific data pipelines." + in first + ) + + +def test_a_hero_button_to_an_unpublished_page_fails(tmp_path: Path): + pages = {"index.md": "# Orcapod\n", "tutorial/index.md": "# Tutorial\n"} + stderr = build_fails(tmp_path, pages, hero=True) + assert "docs/index.md" in stderr + assert "getting-started.md is not a published page" in stderr + + +def test_the_hero_needs_a_home_page(tmp_path: Path): + pages = {"getting-started.md": "# Getting Started\n", "tutorial/index.md": "# T\n"} + assert "the hero needs a home page" in build_fails(tmp_path, pages, hero=True) + + def test_admonitions_become_asides(tmp_path: Path): page = ( "# P\n\n" @@ -275,6 +363,15 @@ def test_linked_file_is_copied(tmp_path: Path): assert (public / "tutorial" / "data.py").read_text() == "print('hi')\n" +def test_the_favicon_is_written_with_the_linked_files(tmp_path: Path): + """The site's favicon (orcapod.org's, in site/src/assets) is in public/ on every build.""" + docs = make_docs(tmp_path, {"index.md": "# Home\n"}) + proc, _, public = run_build(docs, tmp_path) + assert proc.returncode == 0, proc.stderr + favicon = REPO_ROOT / "site" / "src" / "assets" / "favicon.ico" + assert (public / "favicon.ico").read_bytes() == favicon.read_bytes() + + @pytest.mark.parametrize( ("link", "message"), [