Skip to content

Fix documentation page titles #835

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

Closed
tobiasraabe wants to merge 3 commits into from
Closed

Fix documentation page titles #835

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ff4ebce
Fix documentation page titles
tobiasraabe Mar 27, 2026
8209035
Avoid custom YAML tags in docs config
tobiasraabe Mar 27, 2026
3ce504f
Fetch tags before docs install
tobiasraabe Mar 27, 2026
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
3 changes: 2 additions & 1 deletion .readthedocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,14 @@ build:
- asdf plugin add uv
- asdf install uv latest
- asdf global uv latest
- git fetch --tags --force
create_environment:
- uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
install:
- UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
build:
html:
- UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run --group docs zensical build
- UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run --group docs python scripts/run_docs.py build
post_build:
- mkdir -p "${READTHEDOCS_OUTPUT}/html"
- cp -a docs/build/. "${READTHEDOCS_OUTPUT}/html/"
271 changes: 271 additions & 0 deletions docs/theme_overrides/base.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,271 @@
{#-
This file was automatically generated - do not edit
-#}
{% import "partials/language.html" as lang with context %}
<!doctype html>
<html lang="{{ lang.t('language') }}" class="no-js">
<head>
{% block site_meta %}
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
{% if page.meta and page.meta.description %}
<meta name="description" content="{{ page.meta.description }}">
{% elif config.site_description %}
<meta name="description" content="{{ config.site_description }}">
{% endif %}
{% if page.meta and page.meta.author %}
<meta name="author" content="{{ page.meta.author }}">
{% elif config.site_author %}
<meta name="author" content="{{ config.site_author }}">
{% endif %}
{% if page.canonical_url %}
<link rel="canonical" href="{{ page.canonical_url }}">
{% endif %}
{% if page.previous_page %}
<link rel="prev" href="{{ page.previous_page.url | url }}">
{% endif %}
{% if page.next_page %}
<link rel="next" href="{{ page.next_page.url | url }}">
{% endif %}
{% if config.extra.alternate is iterable %}
{% for alt in config.extra.alternate %}
<link rel="alternate" href="{{ alt.link | url }}" hreflang="{{ alt.lang | d(lang.t('language')) }}">
{% endfor %}
{% endif %}
{% set href = config.theme.favicon | d("assets/images/favicon.png") %}
<link rel="icon" href="{{ href | url }}">
<meta name="generator" content="{{ generator }}">
{% endblock %}
{% block htmltitle %}
{% if page.meta and page.meta.title %}
<title>{{ page.meta.title }} - {{ config.site_name }}</title>
{% elif page.title and page.url != "index.html" %}
<title>{{ page.title | striptags }} - {{ config.site_name }}</title>
{% elif config.extra.version %}
<title>{{ config.site_name }} {{ config.extra.version }}</title>
{% else %}
<title>{{ config.site_name }}</title>
{% endif %}
{% endblock %}
{% block styles %}
{% if config.theme.variant == "modern" %}
{% set href = 'assets/stylesheets/modern/main.6f2fbb28.min.css' | url %}
{% else %}
{% set href = 'assets/stylesheets/classic/main.5b14e6eb.min.css' | url %}
{% endif %}
<link rel="stylesheet" href="{{ href }}">
{% if config.theme.palette %}
{% if config.theme.variant == "modern" %}
{% set href = 'assets/stylesheets/modern/palette.dfe2e883.min.css' | url %}
{% else %}
{% set href = 'assets/stylesheets/classic/palette.7dc9a0ad.min.css' | url %}
{% endif %}
<link rel="stylesheet" href="{{ href }}">
{% endif %}
{% include "partials/icons.html" %}
{% endblock %}
{% block libs %}
{% for script in config.extra.polyfills %}
{{ script | script_tag }}
{% endfor %}
{% endblock %}
{% block fonts %}
{% if config.theme.font != false %}
{% set text = config.theme.font.text | d("Roboto", true) %}
{% set code = config.theme.font.code | d("Roboto Mono", true) %}
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family={{
text | replace(' ', '+') + ':300,300i,400,400i,500,500i,700,700i%7C' +
code | replace(' ', '+') + ':400,400i,700,700i'
}}&display=fallback">
<style>:root{--md-text-font:"{{ text }}";--md-code-font:"{{ code }}"}</style>
{% endif %}
{% endblock %}
{% for path in config.extra_css %}
<link rel="stylesheet" href="{{ path | url }}">
{% endfor %}
{% include "partials/javascripts/base.html" %}
{% block analytics %}
{% include "partials/integrations/analytics.html" %}
{% endblock %}
{% block extrahead %}{% endblock %}
</head>
{% set direction = config.theme.direction or lang.t("direction") %}
{% if config.theme.palette %}
{% set palette = config.theme.palette %}
{% if not palette is mapping %}
{% set palette = palette | first %}
{% endif %}
{% set scheme = palette.scheme | d("default", true) %}
{% set primary = palette.primary | d("indigo", true) %}
{% set accent = palette.accent | d("indigo", true) %}
<body dir="{{ direction }}" data-md-color-scheme="{{ scheme | replace(' ', '-') }}" data-md-color-primary="{{ primary | replace(' ', '-') }}" data-md-color-accent="{{ accent | replace(' ', '-') }}">
{% else %}
<body dir="{{ direction }}">
{% endif %}
{% set features = config.theme.features or [] %}
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer" aria-label="{{ lang.t('nav') }}"></label>
<div data-md-component="skip">
{% if page.toc | first is defined %}
{% set skip = page.toc | first %}
<a href="{{ skip.url | url }}" class="md-skip">
{{ lang.t("action.skip") }}
</a>
{% else %}
<a href="#__skip" class="md-skip">
{{ lang.t("action.skip") }}
</a>
{% endif %}
</div>
<div data-md-component="announce">
{% if self.announce() %}
<aside class="md-banner">
<div class="md-banner__inner md-grid md-typeset">
{% if "announce.dismiss" in features %}
<button class="md-banner__button md-icon" aria-label="{{ lang.t('announce.dismiss') }}">
{% set icon = config.theme.icon.close or "material/close" %}
{% include ".icons/" ~ icon ~ ".svg" %}
</button>
{% endif %}
{% block announce %}{% endblock %}
</div>
{% if "announce.dismiss" in features %}
{% include "partials/javascripts/announce.html" %}
{% endif %}
</aside>
{% endif %}
</div>
{% if config.extra.version %}
<div data-md-color-scheme="default" data-md-component="outdated" hidden>
{% if self.outdated() %}
<aside class="md-banner md-banner--warning">
<div class="md-banner__inner md-grid md-typeset">
{% block outdated %}{% endblock %}
</div>
{% include "partials/javascripts/outdated.html" %}
</aside>
{% endif %}
</div>
{% endif %}
{% block header %}
{% include "partials/header.html" %}
{% endblock %}
<div class="md-container" data-md-component="container">
{% block hero %}{% endblock %}
{% block tabs %}
{% if "navigation.tabs.sticky" not in features %}
{% if "navigation.tabs" in features %}
{% include "partials/tabs.html" %}
{% endif %}
{% endif %}
{% endblock %}
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
{% block site_nav %}
{% if nav %}
{% if page.meta and page.meta.hide %}
{% set hidden = "hidden" if "navigation" in page.meta.hide %}
{% endif %}
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" {{ hidden }}>
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
{% include "partials/nav.html" %}
</div>
</div>
</div>
{% endif %}
{% if "toc.integrate" not in features %}
{% if page.meta and page.meta.hide %}
{% set hidden = "hidden" if "toc" in page.meta.hide %}
{% endif %}
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" {{ hidden }}>
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
{% include "partials/toc.html" %}
</div>
</div>
</div>
{% endif %}
{% endblock %}
{% block container %}
<div class="md-content" data-md-component="content">
{% if "navigation.path" in features %}
{% include "partials/path.html" %}
{% endif %}
<article class="md-content__inner md-typeset">
{% block content %}
{% include "partials/content.html" %}
{% endblock %}
</article>
</div>
{% endblock %}
{% include "partials/javascripts/content.html" %}
</div>
{% if "navigation.top" in features %}
{% include "partials/top.html" %}
{% endif %}
</main>
{% block footer %}
{% include "partials/footer.html" %}
{% endblock %}
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
{% if "navigation.instant.progress" in features %}
{% include "partials/progress.html" %}
{% endif %}
{% if config.extra.consent %}
<div class="md-consent" data-md-component="consent" id="__consent" hidden>
<div class="md-consent__overlay"></div>
<aside class="md-consent__inner">
<form class="md-consent__form md-grid md-typeset" name="consent">
{% include "partials/consent.html" %}
</form>
</aside>
</div>
{% include "partials/javascripts/consent.html" %}
{% endif %}
{% block config %}
{% set _ = namespace() %}
{% set _.annotate = config.extra.annotate %}
{% set _.tags = config.extra.tags %}
{%- if config.extra.version -%}
{%- set mike = config.plugins.mike -%}
{%- if not mike or mike.config.version_selector -%}
{%- set _.version = config.extra.version -%}
{%- endif -%}
{%- endif -%}
<script id="__config" type="application/json">
{{- {
"base": base_url,
"features": features,
"translations": {
"clipboard.copy": lang.t("clipboard.copy"),
"clipboard.copied": lang.t("clipboard.copied"),
"search.result.placeholder": lang.t("search.result.placeholder"),
"search.result.none": lang.t("search.result.none"),
"search.result.one": lang.t("search.result.one"),
"search.result.other": lang.t("search.result.other"),
"search.result.more.one": lang.t("search.result.more.one"),
"search.result.more.other": lang.t("search.result.more.other"),
"search.result.term.missing": lang.t("search.result.term.missing"),
"select.version": lang.t("select.version")
},
"search": "assets/javascripts/workers/search.e2d2d235.min.js" | url,
"annotate": _.annotate or none,
"tags": _.tags or none,
"version": _.version or none
} | tojson -}}
</script>
{% endblock %}
{% block scripts %}
<script src="{{ 'assets/javascripts/bundle.c2b142ea.min.js' | url }}"></script>
{% for script in config.extra_javascript %}
{{ script | script_tag }}
{% endfor %}
{% endblock %}
</body>
</html>
4 changes: 2 additions & 2 deletions justfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,12 @@ check: lint typing test
# Build documentation
docs:
uv run --group plugin-list python scripts/update_plugin_list.py
uv run --group docs zensical build
uv run --group docs python scripts/run_docs.py build

# Serve documentation with auto-reload
docs-serve:
uv run --group plugin-list python scripts/update_plugin_list.py
uv run --group docs zensical serve -a 127.0.0.1:8000
uv run --group docs python scripts/run_docs.py serve -a 127.0.0.1:8000

# Run tests with lowest dependency resolution (like CI)
test-lowest:
Expand Down
4 changes: 4 additions & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ nav:

theme:
name: zensical
custom_dir: docs/theme_overrides
logo: _static/images/pytask.svg
favicon: _static/images/pytask.ico
features:
Expand Down Expand Up @@ -170,3 +171,6 @@ extra_css:
extra_javascript:
- _static/js/termynal.js
- _static/js/custom.js

extra:
version: ""
48 changes: 48 additions & 0 deletions scripts/run_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
"""Run docs commands with a temporary config containing the current version."""

from __future__ import annotations

import argparse
import importlib.metadata
import subprocess
import tempfile
from pathlib import Path
from typing import Any

import yaml


def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("command", choices=("build", "serve"))
parser.add_argument("args", nargs="*")
parsed = parser.parse_args()

config_path = Path("mkdocs.yml")
with config_path.open(encoding="utf-8") as fh:
config: dict[str, Any] = yaml.safe_load(fh)

config.setdefault("extra", {})["version"] = importlib.metadata.version("pytask")
with tempfile.NamedTemporaryFile(
mode="w", encoding="utf-8", suffix=".yml", dir=".", delete=False
) as fh:
yaml.safe_dump(config, fh, sort_keys=False)
temporary_config_path = Path(fh.name)

try:
subprocess.run(
[
"zensical",
parsed.command,
"-f",
str(temporary_config_path),
*parsed.args,
],
check=True,
)
finally:
temporary_config_path.unlink(missing_ok=True)


if __name__ == "__main__":
main()
4 changes: 2 additions & 2 deletions src/_pytask/session.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ class Session:
Holds all hooks collected by pytask.
tasks
List of collected tasks.
dag_reports
Reports for resolving dependencies failed.
dag_report
Report for failed dependency resolution.
execution_reports
Reports for executed tasks.
n_tasks_failed
Expand Down
Loading