Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 6 additions & 0 deletions changelog.d/ITL-1170.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
71 changes: 71 additions & 0 deletions docs/dev/specs/2026-11-17-docs-site-theme/README.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
11 changes: 8 additions & 3 deletions scripts/check_site_licenses.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):

Expand All @@ -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",
Expand All @@ -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",
}
)

Expand Down
179 changes: 167 additions & 12 deletions scripts/docs_site_content.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -18,6 +19,11 @@
``docs/`` (``workshop_data.py``) copies the file to the site's static files.
- The ``<!-- docs-test: skip -->`` 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
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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."""

Expand Down Expand Up @@ -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.
"""
Expand All @@ -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:
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading