qdocs 0.2.0__py3-none-any.whl

qdocs/collect.py

@@ -0,0 +1,171 @@
+"""
+Introspection of the documented package: which modules, functions, classes and methods are documented, and where their
+pages live on the website.
+"""
+
+import importlib
+import inspect
+import os
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from typing import Any
+
+from qdocs.project import Project
+
+
+@dataclass
+class Entry:
+    """A documented function, class, namespace or method."""
+
+    name: str
+    obj: Any  # The function, class or method. None for modules.
+    module: str  # The module (file) this entry is documented in, e.g. "analyze".
+    namespace: str  # The public namespace, e.g. "qspec.analyze" or "qspec.models.Model".
+    url: str  # The site url of the page, e.g. "/doc/functions/analyze/york_fit.html".
+    kind: str  # "function", "class", "namespace", "method" or "module" (only used as a reference target).
+    owner: "Entry | None" = None  # The class of a method.
+    methods: list["Method"] = field(default_factory=list)  # The methods of a class.
+
+    @property
+    def qualname(self) -> str:
+        return f"{self.namespace}.{self.name}"
+
+    @property
+    def func(self) -> Callable[..., Any] | None:
+        """
+        The function whose signature and docstring describe this entry. For a class this is `__init__`, or `__new__`
+        if only that is overridden. None for a class that overrides neither.
+        """
+        if self.kind != "class":
+            return self.obj
+        for name in ("__init__", "__new__"):
+            func = getattr(self.obj, name)
+            if func is not getattr(object, name):
+                return func
+        return None
+
+
+@dataclass
+class Method:
+    """A public method of a class, either defined in that class (page) or inherited (link to the defining class)."""
+
+    name: str
+    entry: Entry  # The entry of the page that documents this method.
+    inherited_from: Entry | None = None  # The documented class the method is inherited from.
+
+
+@dataclass
+class Module:
+    name: str
+    url: str
+    entries: list[Entry]
+
+
+def _public_methods(cls: type) -> list[str]:
+    return [name for name, _ in inspect.getmembers(cls, inspect.isfunction) if not name.startswith("_")]
+
+
+def _defining_class(cls: type, name: str) -> type:
+    for c in cls.__mro__:
+        if name in vars(c):
+            return c
+    return cls
+
+
+def collect(project: Project) -> list[Module]:
+    """
+    :param project: The documented project.
+    :returns: The documented modules with their functions and classes. Class methods are only documented on the page
+     of the class that defines them, as long as that class is documented itself.
+    """
+    modules = []
+    classes = {}  # class object -> Entry
+    for file in project.modules:
+        mod = importlib.import_module(f"{project.package}.{file}")
+        namespace = f"{project.package}.{file}" if file in project.namespaced else project.package
+        include = project.include.get(file)
+        names = sorted(n for n in mod.__all__ if callable(getattr(mod, n)) and (include is None or n in include))
+        entries = []
+        for name in names:
+            obj = getattr(mod, name)
+            if f"{namespace}.{name}" in project.namespaces:
+                entry = Entry(name, obj, file, namespace, f"/doc/functions/{file}/{name}.html", "namespace")
+            elif inspect.isclass(obj):
+                entry = Entry(name, obj, file, namespace, f"/doc/functions/{file}/{name}/{name}.html", "class")
+                classes[obj] = entry
+            else:
+                entry = Entry(name, obj, file, namespace, f"/doc/functions/{file}/{name}.html", "function")
+            entries.append(entry)
+        modules.append(Module(file, f"/doc/modules/{file}.html", entries))
+
+    # Methods are resolved after all classes are known, so inherited methods can link across modules.
+    for cls, entry in classes.items():
+        for name in _public_methods(cls):
+            definer = classes.get(_defining_class(cls, name))
+            if definer is None or definer is entry:
+                url = f"/doc/functions/{entry.module}/{entry.name}/{name}.html"
+                m_entry = Entry(name, getattr(cls, name), entry.module, entry.qualname, url, "method", owner=entry)
+                entry.methods.append(Method(name, m_entry))
+            else:
+                entry.methods.append(Method(name, None, inherited_from=definer))  # type: ignore
+
+    # Resolve the entries of inherited methods once all own methods exist.
+    for entry in classes.values():
+        for m in entry.methods:
+            if m.inherited_from is not None:
+                m.entry = next(_m.entry for _m in m.inherited_from.methods if _m.name == m.name)
+    return modules
+
+
+def iter_pages(modules: list[Module]) -> Iterator[Entry]:
+    """Yield every entry that gets its own page."""
+    for module in modules:
+        for entry in module.entries:
+            yield entry
+            for m in entry.methods:
+                if m.inherited_from is None:
+                    yield m.entry
+
+
+def build_index(project: Project, modules: list[Module]) -> dict[str, list[Entry]]:
+    """
+    :param project: The documented project.
+    :param modules: The documented modules.
+    :returns: A map from every name an entry can be referenced by in docstrings to the matching entries.
+     Names are the short name (`fit`), `Class.method`, the fully qualified name (`qspec.models.fit`)
+     and the module names (`qspec.analyze`).
+    """
+    index: dict[str, list[Entry]] = {}
+    package = project.package
+
+    def add(key: str, entry: Entry) -> None:
+        bucket = index.setdefault(key, [])
+        if entry not in bucket:
+            bucket.append(entry)
+
+    for entry in iter_pages(modules):
+        add(entry.name, entry)
+        add(entry.qualname, entry)
+        # Entries of modules in the package namespace are also reachable through their module, e.g. qspec.physics.f.
+        add(entry.qualname.replace(f"{package}.", f"{package}.{entry.module}.", 1), entry)
+        if entry.owner is not None:
+            add(f"{entry.owner.name}.{entry.name}", entry)
+    for module in modules:
+        add(f"{package}.{module.name}", Entry(module.name, None, module.name, package, module.url, "module"))
+        for entry in module.entries:
+            for m in entry.methods:  # Inherited methods are also reachable as Subclass.method.
+                add(f"{entry.name}.{m.name}", m.entry)
+                add(f"{entry.qualname}.{m.name}", m.entry)
+    return index
+
+
+def source_location(project: Project, obj: Any) -> tuple[str, int, int]:
+    """
+    :param project: The documented project.
+    :param obj: A function or class.
+    :returns: (path, start, stop) The path of the source file relative to the repository root (posix style)
+     and the first and last line of the object.
+    """
+    lines, start = inspect.getsourcelines(obj)
+    path = os.path.relpath(inspect.getfile(obj), project.root).replace(os.sep, "/")
+    return path, start, start + len(lines) - 1

qdocs/docstring.py

@@ -0,0 +1,108 @@
+"""
+A parser for the reST field style of the docstrings:
+
+    Description, possibly over several paragraphs.
+
+    :param name: Description, continued on
+     indented lines.
+    :returns: (label) Description. The optional label in parentheses names the return value(s).
+    :raises ValueError: Description.
+    :raises (ValueError, TypeError): Description.
+"""
+
+import inspect
+import re
+from dataclasses import dataclass, field
+
+FIELD = re.compile(r"^:(\w+)(?:\s+([^:]+?))?\s*:(?:\s+(.*))?$")
+FIELD_KINDS = {
+    "param": "param",
+    "returns": "returns",
+    "return": "returns",
+    "raises": "raises",
+    "raise": "raises",
+}
+
+
+@dataclass
+class Returns:
+    label: str
+    description: str
+
+
+@dataclass
+class Docstring:
+    description: str = ""
+    params: dict[str, str] = field(default_factory=dict)
+    returns: Returns | None = None
+    raises: list[tuple[str, str]] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def _split_label(text: str) -> tuple[str, str]:
+    """Split a leading '(label)' from a returns description. A single name loses its parentheses."""
+    if not text.startswith("("):
+        return "out", text
+    j = text.find(")") + 1
+    label = text[:j]
+    if "," not in label:
+        label = label[1:-1]
+    return label, text[j:].strip()
+
+
+def parse(doc: str | None) -> Docstring:
+    ret = Docstring()
+    if not doc:
+        return ret
+
+    description: list[str] = []
+    fields: list[tuple[str, str, list[str]]] = []  # (kind, argument, lines)
+    for line in inspect.cleandoc(doc).splitlines():
+        m = FIELD.match(line)
+        if m:
+            name, arg, text = m.group(1), (m.group(2) or "").strip(), m.group(3) or ""
+            kind = FIELD_KINDS.get(name)
+            if kind is None:
+                ret.warnings.append(f"unknown field ':{name}:'")
+                kind = name
+            fields.append((kind, arg, [text]))
+        elif fields:
+            fields[-1][2].append(line)
+        else:
+            description.append(line)
+
+    ret.description = "\n".join(description).strip()
+    for kind, arg, lines in fields:
+        # Continuation lines are indented relative to the field. Remove the common indentation.
+        text = lines[0] + ("\n" + inspect.cleandoc("\n".join(lines[1:])) if len(lines) > 1 else "")
+        text = text.strip()
+        if kind == "param":
+            if arg in ret.params:
+                ret.warnings.append(f"parameter '{arg}' documented twice")
+            ret.params[arg] = text
+        elif kind == "returns":
+            if ret.returns is not None:
+                ret.warnings.append("':returns:' documented twice")
+            ret.returns = Returns(*_split_label(text))
+        elif kind == "raises":
+            ret.raises.append((arg, text))
+    return ret
+
+
+def validate(doc: Docstring, params: list[str], is_class: bool) -> list[str]:
+    """
+    :param doc: The parsed docstring.
+    :param params: The parameter names of the signature (without self).
+    :param is_class: Whether the docstring belongs to a class (no ':returns:' expected).
+    :returns: Warnings about mismatches between the docstring and the signature.
+    """
+    warnings = list(doc.warnings)
+    for p in doc.params:
+        if p not in params:
+            warnings.append(f"documented parameter '{p}' is not in the signature")
+    for p in params:
+        if p not in doc.params:
+            warnings.append(f"parameter '{p}' is not documented")
+    if is_class and doc.returns is not None:
+        warnings.append("class documents ':returns:'")
+    return warnings

qdocs/markup.py

@@ -0,0 +1,96 @@
+"""
+Conversion of docstring prose to HTML. Supported markup:
+
+- `code`
+- [`name`] references to other documented objects
+- $inline$ and $$block$$ LaTeX math (rendered by MathJax on the website)
+- blank lines separate paragraphs, lines starting with '- ' form lists
+- raw HTML, e.g. <a href="https://doi.org/...">...</a>, is passed through
+"""
+
+import html
+import re
+from collections.abc import Callable
+
+BLOCK_MATH = re.compile(r"\$\$(.+?)\$\$", re.DOTALL)
+INLINE_MATH = re.compile(r"(?<![\\$])\$(?!\$)(.+?)(?<![\\$])\$", re.DOTALL)
+REF = re.compile(r"\[`([^`]+)`\]")
+CODE = re.compile(r"`([^`]+)`")
+PLACEHOLDER = re.compile(r"\x00(\d+)\x00")
+
+
+def _escape(text: str) -> str:
+    return html.escape(text, quote=False)
+
+
+class Converter:
+    def __init__(self, resolve: Callable[[str], str]) -> None:
+        """
+        :param resolve: Returns the site url of a referenced name. Must raise a `KeyError` for unknown names.
+        """
+        self.resolve = resolve
+
+    def __call__(self, text: str) -> str:
+        stash: list[tuple[str, str]] = []  # (kind, html)
+
+        def put(kind: str, value: str) -> str:
+            stash.append((kind, value))
+            return f"\x00{len(stash) - 1}\x00"
+
+        text = BLOCK_MATH.sub(lambda m: put("block", f"$${_escape(m.group(1))}$$"), text)
+        text = INLINE_MATH.sub(lambda m: put("inline", f"${_escape(m.group(1))}$"), text)
+        text = REF.sub(lambda m: put("inline", self._ref(m.group(1))), text)
+        text = CODE.sub(lambda m: put("inline", f"<code>{_escape(m.group(1))}</code>"), text)
+
+        out = []
+        for block in re.split(r"\n\s*\n", text.strip()):
+            out.extend(self._block(block, stash))
+        ret = "\n".join(out)
+        return PLACEHOLDER.sub(lambda m: stash[int(m.group(1))][1], ret)
+
+    def _ref(self, name: str) -> str:
+        url = self.resolve(name)
+        return f"<a href=\"{{{{ '{url}' | relative_url }}}}\"><code>{_escape(name)}</code></a>"
+
+    @staticmethod
+    def _block(block: str, stash: list[tuple[str, str]]) -> list[str]:
+        """Split a block into paragraphs, block math and lists."""
+        out = []
+        para: list[str] = []
+        items: list[list[str]] = []
+
+        def flush_para() -> None:
+            if para:
+                out.append("<p>" + "\n".join(para) + "</p>")
+                para.clear()
+
+        def flush_items() -> None:
+            if items:
+                out.append("<ul>" + "".join("<li>" + "\n".join(i) + "</li>" for i in items) + "</ul>")
+                items.clear()
+
+        for line in block.splitlines():
+            stripped = line.strip()
+            # Block math always stands on its own, even if written inside a sentence.
+            parts = re.split(r"(\x00\d+\x00)", stripped)
+            if any(stash[int(p[1:-1])][0] == "block" for p in parts if PLACEHOLDER.fullmatch(p)):
+                flush_items()
+                for p in parts:
+                    if PLACEHOLDER.fullmatch(p) and stash[int(p[1:-1])][0] == "block":
+                        flush_para()
+                        out.append(f'<div class="math-block">{p}</div>')
+                    elif p.strip():
+                        para.append(p.strip())
+                continue
+            if stripped.startswith("- "):
+                flush_para()
+                items.append([stripped[2:]])
+            elif items and line[:1].isspace():
+                items[-1].append(stripped)
+            else:
+                flush_items()
+                if stripped:
+                    para.append(stripped)
+        flush_para()
+        flush_items()
+        return out

qdocs/project.py

@@ -0,0 +1,45 @@
+"""
+The configuration of a documented package.
+"""
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Project:
+    """
+    The package and the website it is documented on. The website is a Jekyll site in `docs` that uses the qdocs theme.
+
+    :param package: The name of the documented package, e.g. "qspec".
+    :param modules: The documented modules (files or folders) of the package, e.g. ["algebra", "analyze"].
+    :param root: The repository root. Source links on the website are relative to it.
+    :param namespaced: The modules that are their own namespace (qspec.models.Model).
+     The entries of the other modules live in the package namespace (qspec.fit).
+    :param include: The modules for which only the listed names are documented.
+    :param namespaces: The fully qualified names of classes that are documented as a namespace of attributes
+     (no signature, no methods), e.g. a registry class used like a module. Enums are documented this way, too.
+    :param type_aliases: The module whose type aliases and classes are linked to its module page in annotations.
+    :param branch: The branch of the source links.
+    :param docs: The Jekyll site. Defaults to `root/docs`.
+    :param examples: The example scripts with the tutorial code regions. Defaults to `root/examples`.
+    :param logo: The light logo of the site, relative to `docs`. The `logo` target derives the dark logo from it.
+    """
+
+    package: str
+    modules: list[str]
+    root: str
+    namespaced: set[str] = field(default_factory=set)
+    include: dict[str, set[str]] = field(default_factory=dict)
+    namespaces: set[str] = field(default_factory=set)
+    type_aliases: str | None = None
+    branch: str = "main"
+    docs: str = ""
+    examples: str = ""
+    logo: str = "assets/img/logo.svg"
+
+    def __post_init__(self) -> None:
+        self.root = os.path.abspath(self.root)
+        self.docs = os.path.abspath(self.docs or os.path.join(self.root, "docs"))
+        self.examples = os.path.abspath(self.examples or os.path.join(self.root, "examples"))
+        self.modules = sorted(self.modules)

qdocs/templates/function.html

@@ -0,0 +1,74 @@
+---
+layout: api
+title: [[ title ]]
+---
+<dl class="py function">
+<dt class="func-sig">
+<span class="sig-prename">[[ prename ]].</span>
+[%- if classname %]<span class="sig-classname">[[ classname ]]</span><span class="sig-prename">.</span>[% endif %]
+<span class="[[ 'sig-classname' if is_class else 'sig-name' ]]">[[ name ]]</span>
+[%- if has_sig %]
+<span class="sig-paren">&nbsp;(&nbsp;</span>
+[%- for p in sig %]
+<em class="sig-param">
+[%- if p.star %]<span class="o">[[ p.star ]]</span>[% endif %]<span class="n">[[ p.name ]]</span>
+[%- if p.default is not none %]<span class="o">=</span>[[ p.default ]][% endif -%]
+</em>
+[%- if not loop.last %]
+,&nbsp;
+[%- endif %]
+[%- endfor %]
+<span class="sig-paren">&nbsp;)</span>
+[%- endif %]<a href="{{ site.github.repository_url | append: '/blob/[[ source.branch ]]/[[ source.path ]]#L[[ source.start ]]-L[[ source.stop ]]' }}"><span class="sig-source">[source]</span></a>
+</dt>
+<dd class="field-body">
+[[ description ]]
+<dl class="field-list">
+[%- if params %]
+<dt class="field-head">Parameters<span class="colon">:</span></dt>
+<dd class="field-par">
+<dl>
+[%- for p in params %]
+<dt>[[ p.name ]][% if p.type %]<span class="classifier"><em>[[ p.type ]]</em></span>[% endif %]</dt>
+<dd class="field-desc">[[ p.description ]]</dd>
+[%- endfor %]
+</dl>
+</dd>
+[%- endif %]
+[%- if attributes %]
+<dt class="field-head">Attributes<span class="colon">:</span></dt>
+<dd class="field-par">
+<dl>
+[%- for a in attributes %]
+<dt>[[ a.name ]][% if a.type %]<span class="classifier"><em>[[ a.type ]]</em></span>[% endif %]
+[%- if a.value is not none %]<span class="attr-value">[[ a.value ]]</span>[% endif %]</dt>
+[%- if a.description %]
+<dd class="field-desc">[[ a.description ]]</dd>
+[%- endif %]
+[%- endfor %]
+</dl>
+</dd>
+[%- endif %]
+[%- if returns %]
+<dt class="field-head">Returns<span class="colon">:</span></dt>
+<dd class="field-par">
+<dl>
+<dt>[[ returns.label ]][% if returns.type %]<span class="classifier"><em>[[ returns.type ]]</em></span>[% endif %]</dt>
+<dd class="field-desc">[[ returns.description ]]</dd>
+</dl>
+</dd>
+[%- endif %]
+[%- if raises %]
+<dt class="field-head">Raises<span class="colon">:</span></dt>
+<dd class="field-par">
+<dl>
+[%- for r in raises %]
+<dt>[[ r.error ]]</dt>
+<dd class="field-desc">[[ r.description ]]</dd>
+[%- endfor %]
+</dl>
+</dd>
+[%- endif %]
+</dl>
+</dd>
+</dl>

qdocs/templates/nav.html

@@ -0,0 +1,37 @@
+[#- The API navigation tree. Generated once and included by the api layout; script.js marks the current page. -#]
+<ul class="extern">
+[%- for module in modules %]
+  <li class="has-children">
+    <a href="{{ '[[ module.url ]]' | relative_url }}">[[ package ]].[[ module.name ]]</a>
+    <details>
+      <summary aria-label="Show the contents of [[ package ]].[[ module.name ]]">
+        <span class="toctree-toggle" role="presentation"><img src="{{ '/assets/img/chevron-down.svg' | relative_url }}" class="chevron" alt=""/></span>
+      </summary>
+      <ul class="extern-a">
+      [%- for entry in module.entries %]
+      [%- if entry.methods %]
+        <li class="has-children spaced"><a href="{{ '[[ entry.url ]]' | relative_url }}">[[ entry.qualname ]]</a>
+          <details>
+            <summary aria-label="Show the methods of [[ entry.name ]]">
+              <span class="toctree-toggle" role="presentation"><img src="{{ '/assets/img/chevron-down.svg' | relative_url }}" class="chevron" alt=""/></span>
+            </summary>
+            <ul class="extern-a">
+            [%- for m in entry.methods %]
+              [%- if m.inherited_from %]
+              <li class="indent-a"><a class="inherited" href="{{ '[[ m.entry.url ]]' | relative_url }}" title="Inherited from [[ m.inherited_from.qualname ]]">[[ entry.qualname ]].[[ m.name ]] <span class="nav-inherited">([[ m.inherited_from.name ]])</span></a></li>
+              [%- else %]
+              <li class="indent-a"><a href="{{ '[[ m.entry.url ]]' | relative_url }}">[[ entry.qualname ]].[[ m.name ]]</a></li>
+              [%- endif %]
+            [%- endfor %]
+            </ul>
+          </details>
+        </li>
+      [%- else %]
+        <li class="spaced"><a href="{{ '[[ entry.url ]]' | relative_url }}">[[ entry.qualname ]]</a></li>
+      [%- endif %]
+      [%- endfor %]
+      </ul>
+    </details>
+  </li>
+[%- endfor %]
+</ul>

qdocs/tutorials.py

@@ -0,0 +1,115 @@
+"""
+Highlighted tutorial code blocks from marked regions in the example scripts:
+
+    # docs: hfs-0
+    import qspec as qs
+    ...
+    # docs: end
+
+Each region becomes docs/_includes/code/<name>.html, which a tutorial page includes with
+{% include code/<name>.html %}. A file may contain several regions.
+"""
+
+import glob
+import os
+import re
+import textwrap
+from collections.abc import Callable
+
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import get_lexer_by_name
+from pygments.styles import get_style_by_name
+
+from qdocs.project import Project
+
+STYLE = "catppuccin-latte"
+STYLE_DARK = "catppuccin-mocha"
+MARKER = re.compile(r"^\s*# docs: (\S+)\s*$")
+INCLUDE = re.compile(r"{%\s*include\s+code/(\S+?)\.html\s*%}")
+
+
+def find_regions(paths: list[str]) -> tuple[dict[str, str], list[str]]:
+    """
+    :param paths: The paths of the example scripts.
+    :returns: (regions, errors) The code of each region by name and a list of errors.
+    """
+    regions: dict[str, str] = {}
+    errors = []
+    for path in paths:
+        name, start, lines = None, 0, []
+        with open(path, encoding="utf-8") as f:
+            for i, line in enumerate(f.read().splitlines(), start=1):
+                m = MARKER.match(line)
+                if m is None:
+                    if name is not None:
+                        lines.append(line)
+                elif m.group(1) == "end":
+                    if name is None:
+                        errors.append(f"{path}:{i}: '# docs: end' without an open region")
+                        continue
+                    if name in regions:
+                        errors.append(f"{path}:{start}: duplicate region '{name}'")
+                    regions[name] = textwrap.dedent("\n".join(lines)).strip("\n")
+                    name, lines = None, []
+                else:
+                    if name is not None:
+                        errors.append(f"{path}:{i}: region '{m.group(1)}' starts inside region '{name}'")
+                    name, start, lines = m.group(1), i, []
+        if name is not None:
+            errors.append(f"{path}:{start}: region '{name}' is not closed")
+    return regions, errors
+
+
+def to_html(code: str) -> str:
+    lexer = get_lexer_by_name("python", stripall=True)
+    formatter = HtmlFormatter(cssclass="py-source", style=get_style_by_name(STYLE))
+    return highlight(code, lexer, formatter)
+
+
+def build(project: Project, write: Callable[[str, str], None]) -> list[str]:
+    """
+    :param project: The documented project.
+    :param write: A function `write(path, text)`.
+    :returns: A list of errors.
+    """
+    regions, errors = find_regions(sorted(glob.glob(os.path.join(project.examples, "*.py"))))
+    out_dir = os.path.join(project.docs, "_includes", "code")
+    for f in glob.glob(os.path.join(out_dir, "*.html")):
+        os.remove(f)
+    for name, code in regions.items():
+        write(os.path.join(out_dir, f"{name}.html"), to_html(code))
+    print(f"Wrote {len(regions)} tutorial code blocks.")
+
+    used = set()
+    for page in sorted(glob.glob(os.path.join(project.docs, "tutorials", "*.html"))):
+        with open(page, encoding="utf-8") as f:
+            for name in INCLUDE.findall(f.read()):
+                used.add(name)
+                if name not in regions:
+                    errors.append(f"{os.path.relpath(page, project.root)}: no region '{name}' in examples/")
+    for name in sorted(set(regions) - used):
+        print(f"  note: region '{name}' is not included by any tutorial page")
+    return errors
+
+
+def pycode_css() -> str:
+    """
+    :returns: The SCSS of the light (STYLE) and the dark (STYLE_DARK) code highlighting.
+     The dark style applies under the same conditions as the dark colors in assets/css/style.scss.
+     Both use the code block background of the page instead of the background of the style.
+    """
+    # The selector argument is needed to also get the default text color of the style ('.py-source { color: ... }').
+    light = HtmlFormatter(cssclass="py-source", style=get_style_by_name(STYLE)).get_style_defs(".py-source")
+    dark = HtmlFormatter(cssclass="py-source", style=get_style_by_name(STYLE_DARK)).get_style_defs(".py-source")
+    bg = ".py-source { background-color: var(--pre-bg-color); }"
+    dark = textwrap.indent(f"{dark}\n{bg}", "    ")  # type: ignore
+    return (
+        f"// Light mode: {STYLE}.\n{light}\n{bg}\n\n"
+        f"// Dark mode: {STYLE_DARK}.\n"
+        f"@mixin pycode-dark {{\n{dark}\n}}\n\n"
+        ':root[data-theme="dark"] { @include pycode-dark; }\n'
+        "@media (prefers-color-scheme: dark) {\n"
+        '    :root:not([data-theme="light"]) { @include pycode-dark; }\n'
+        "}\n"
+    )