qdocs 0.2.0__py3-none-any.whl

qdocs/__init__.py

@@ -0,0 +1,8 @@
+"""
+The website theme and generator of qspec and qunits.
+"""
+
+from qdocs.build import ApiBuilder, Attribute, main
+from qdocs.project import Project
+
+__all__ = ["ApiBuilder", "Attribute", "Project", "main"]

qdocs/__main__.py

@@ -0,0 +1,75 @@
+"""
+Commands for the theme itself. Run from a checkout of the qdocs repository:
+
+    python -m qdocs css
+    python -m qdocs preview <docs> [build | serve] [jekyll options]
+
+- css: the Pygments styles _sass/qdocs/pycode.scss.
+- preview: builds or serves a site with the theme of this checkout instead of its remote_theme, e.g. to try theme
+  changes before they are pushed. The site and the theme are copied into a temporary folder, rerun after changes.
+"""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from qdocs import tutorials
+from qdocs.build import write
+
+THEME = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+THEME_DIRS = ["_layouts", "_includes", "_sass", "assets"]
+PYCODE_FILE = os.path.join(THEME, "_sass", "qdocs", "pycode.scss")
+
+
+def preview(docs: str, command: str, options: list[str]) -> int:
+    docs = os.path.abspath(docs)
+    site = os.path.join(tempfile.gettempdir(), "qdocs-preview", os.path.basename(os.path.dirname(docs)))
+    if os.path.exists(site):
+        shutil.rmtree(site)
+    for d in THEME_DIRS:
+        shutil.copytree(os.path.join(THEME, d), os.path.join(site, d))
+    ignore = shutil.ignore_patterns("_site", ".jekyll-cache", ".jekyll-metadata")
+    shutil.copytree(docs, site, ignore=ignore, dirs_exist_ok=True)  # Files of the site override the theme.
+
+    config = os.path.join(site, "_config.yml")
+    with open(config, encoding="utf-8") as f:
+        text = re.sub(r"^remote_theme:.*$", "", f.read(), flags=re.MULTILINE)
+    write(config, text)
+
+    env = dict(os.environ, BUNDLE_GEMFILE=os.path.join(docs, "Gemfile"))
+    # The copy is not a git repository, site.github needs the repository of the site.
+    origin = subprocess.run(
+        ["git", "-C", docs, "remote", "get-url", "origin"], capture_output=True, text=True, check=False
+    ).stdout
+    m = re.search(r"github\.com[:/](.+?)(?:\.git)?\s*$", origin)
+    if m and "PAGES_REPO_NWO" not in env:
+        env["PAGES_REPO_NWO"] = m.group(1)
+    args = ["bundle", "exec", "jekyll", command, "-d", os.path.join(site, "_site"), *options]
+    print(f"Running {' '.join(args)} in {site}")
+    return subprocess.call(args, cwd=site, env=env, shell=sys.platform == "win32")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Commands for the qdocs theme.")
+    sub = parser.add_subparsers(dest="target", required=True)
+    sub.add_parser("css", help="Generate _sass/qdocs/pycode.scss.")
+    p = sub.add_parser("preview", help="Build or serve a site with the theme of this checkout.")
+    p.add_argument("docs", help="The Jekyll site, e.g. ../qspec/docs.")
+    p.add_argument("command", nargs="?", default="serve", choices=["build", "serve"])
+    args, options = parser.parse_known_args()
+
+    if not os.path.isdir(os.path.join(THEME, "_sass", "qdocs")):
+        sys.exit("The theme files are not next to the qdocs package. Run this from a checkout of the repository.")
+    if args.target == "css":
+        write(PYCODE_FILE, tutorials.pycode_css())
+        print(f"Wrote {os.path.relpath(PYCODE_FILE, THEME)}.")
+    else:
+        sys.exit(preview(args.docs, args.command, options))
+
+
+if __name__ == "__main__":
+    main()

qdocs/annotations.py

@@ -0,0 +1,140 @@
+"""
+Type annotations exactly as written in the source code, with documented classes and type aliases linked.
+"""
+
+import ast
+import html
+import importlib
+import inspect
+import re
+import textwrap
+from collections.abc import Callable
+from typing import Any
+
+IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_.]*")
+
+
+def module_aliases(module: str) -> set[str]:
+    """
+    :param module: The fully qualified name of a module.
+    :returns: The type aliases (`type x = ...`, `x = ...`) and classes defined in the module.
+    """
+    tree = ast.parse(inspect.getsource(importlib.import_module(module)))
+    names = set()
+    for node in tree.body:
+        if isinstance(node, ast.TypeAlias):
+            names.add(node.name.id)  # type: ignore
+        elif isinstance(node, ast.Assign):
+            names.update(t.id for t in node.targets if isinstance(t, ast.Name) and not t.id.startswith("_"))
+        elif isinstance(node, ast.ClassDef):
+            names.add(node.name)
+    return names - {"__all__"}
+
+
+def _strip_quotes(text: str) -> str:
+    if len(text) >= 2 and text[0] == text[-1] and text[0] in "'\"":
+        return text[1:-1]
+    return text
+
+
+def source_annotations(func: Callable[..., Any]) -> tuple[dict[str, str], str | None]:
+    """
+    :param func: A function or method.
+    :returns: (params, returns) The annotation source text of each annotated parameter
+     and of the return value (`None` if not annotated).
+    """
+    try:
+        source = textwrap.dedent(inspect.getsource(func))
+        node = ast.parse(source).body[0]
+    except (OSError, TypeError, SyntaxError, IndexError):
+        return _fallback(func)
+    if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return _fallback(func)
+
+    args = node.args
+    params = {}
+    for arg in [*args.posonlyargs, *args.args, args.vararg, *args.kwonlyargs, args.kwarg]:
+        if arg is not None and arg.annotation is not None:
+            params[arg.arg] = _strip_quotes(ast.get_source_segment(source, arg.annotation))  # type: ignore
+    returns = None
+    if node.returns is not None:
+        returns = _strip_quotes(ast.get_source_segment(source, node.returns))  # type: ignore
+    return params, returns
+
+
+def class_attributes(cls: type) -> dict[str, tuple[str | None, str]]:
+    """
+    :param cls: A class.
+    :returns: (annotation, description) The annotation source text (`None` if not annotated) and the docstring below
+     the attribute ("" if there is none) of each attribute that is assigned or annotated in the body of the class or
+     of its bases. A subclass inherits the annotation and the docstring of an attribute it only reassigns.
+    """
+    ret: dict[str, tuple[str | None, str]] = {}
+    for c in reversed(cls.__mro__[:-1]):  # Bases first, without object.
+        try:
+            source = textwrap.dedent(inspect.getsource(c))
+            node = ast.parse(source).body[0]
+        except (OSError, TypeError, SyntaxError, IndexError):
+            continue  # Builtins and classes created at runtime.
+        if not isinstance(node, ast.ClassDef):
+            continue
+        for stmt, after in zip(node.body, [*node.body[1:], None]):
+            if isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+                names = [stmt.target.id]
+                annotation = _strip_quotes(ast.get_source_segment(source, stmt.annotation))  # type: ignore
+            elif isinstance(stmt, ast.Assign):
+                names, annotation = [t.id for t in stmt.targets if isinstance(t, ast.Name)], None
+            else:
+                continue
+            doc = ""
+            if isinstance(after, ast.Expr) and isinstance(getattr(after.value, "value", None), str):
+                doc = inspect.cleandoc(after.value.value)  # type: ignore
+            for name in names:
+                base_annotation, base_doc = ret.get(name, (None, ""))
+                ret[name] = (annotation or base_annotation, doc or base_doc)
+    return ret
+
+
+def _fallback(func: Callable[..., Any]) -> tuple[dict[str, str], str | None]:
+    sig = inspect.signature(func)
+    params = {
+        name: inspect.formatannotation(p.annotation)
+        for name, p in sig.parameters.items()
+        if p.annotation is not inspect.Parameter.empty
+    }
+    returns = None
+    if sig.return_annotation is not inspect.Signature.empty:
+        returns = inspect.formatannotation(sig.return_annotation)
+    return params, returns
+
+
+class Linker:
+    def __init__(self, class_urls: dict[str, str], aliases: set[str] = frozenset(), aliases_url: str = "") -> None:  # type: ignore
+        """
+        :param class_urls: A map from class names (short and fully qualified) to their site urls.
+        :param aliases: The names of type aliases, linked to `aliases_url`.
+        :param aliases_url: The site url of the module page that describes the type aliases.
+        """
+        self.class_urls = class_urls
+        self.aliases = aliases
+        self.aliases_url = aliases_url
+
+    def __call__(self, annotation: str) -> str:
+        """
+        :param annotation: The annotation source text.
+        :returns: The HTML of the annotation with documented classes and type aliases linked.
+        """
+        out = []
+        last = 0
+        for m in IDENTIFIER.finditer(annotation):
+            name = m.group(0)
+            url = self.class_urls.get(name)
+            if url is None and name in self.aliases:
+                url = self.aliases_url
+            if url is None:
+                continue
+            out.append(html.escape(annotation[last : m.start()]))
+            out.append(f"<a href=\"{{{{ '{url}' | relative_url }}}}\">{html.escape(name)}</a>")
+            last = m.end()
+        out.append(html.escape(annotation[last:]))
+        return "".join(out)

qdocs/build.py

@@ -0,0 +1,316 @@
+"""
+Generates the generated parts of a website that uses the qdocs theme. A site calls `main` from its build script:
+
+    python docs/_gen/build.py [api | tutorials | logo | all]
+
+- api: the API pages in docs/doc/functions/ and the navigation docs/_includes/api-nav.html.
+- tutorials: the highlighted code blocks docs/_includes/code/*.html from the marked regions in examples/*.py.
+- logo: the dark mode logo (logo_dark.svg) from the light one (logo.svg).
+"""
+
+import argparse
+import enum
+import html
+import inspect
+import os
+import re
+import shutil
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+from qdocs import annotations, collect, docstring, markup, tutorials
+from qdocs.project import Project
+
+# Jinja delimiters that do not clash with the Liquid syntax ({{ }}, {% %}) that Jekyll renders afterward.
+env = Environment(
+    loader=FileSystemLoader(os.path.join(os.path.dirname(os.path.abspath(__file__)), "templates")),
+    block_start_string="[%",
+    block_end_string="%]",
+    variable_start_string="[[",
+    variable_end_string="]]",
+    comment_start_string="[#",
+    comment_end_string="#]",
+    undefined=StrictUndefined,
+    keep_trailing_newline=True,
+)
+
+# The colors of the light logo and their replacements in the dark logo.
+DARK_LOGO_COLORS = {"#000000": "#e8e6ed", "#808080": "#a9a6b0"}
+
+# The value of an attribute that has none on the class, e.g. an instance attribute or a property.
+EMPTY = inspect.Parameter.empty
+
+
+@dataclass
+class Attribute:
+    """An attribute listed on the page of a class."""
+
+    name: str
+    value: Any = EMPTY
+    type: str | None = None  # The annotation source text.
+    description: str = ""
+
+
+def write(path: str, text: str) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8", newline="\n") as f:
+        f.write(text)
+
+
+def _default(value: Any) -> tuple[str, str]:
+    """
+    :returns: (text, color_class) The HTML text of a default value and the CSS class that colors it.
+    """
+    if isinstance(value, bool):
+        return str(value), "bool"
+    if isinstance(value, str):
+        return html.escape(repr(value)), "string"  # Quotes and control characters as in the source.
+    if isinstance(value, (int, float, tuple)):
+        return html.escape(str(value)), "num"
+    if callable(value):
+        return html.escape(value.__name__), ""
+    return html.escape(str(value)), ""
+
+
+def _is_enum(obj: Any) -> bool:
+    return inspect.isclass(obj) and issubclass(obj, enum.Enum)
+
+
+class ApiBuilder:
+    """
+    Builds the API pages of a project. Subclass it to customize how attributes and values are shown,
+    see `attributes` and `format_value`.
+    """
+
+    def __init__(self, project: Project) -> None:
+        self.project = project
+        self.modules = collect.collect(project)
+        self.index = collect.build_index(project, self.modules)
+        self.errors: list[str] = []
+        self.warnings: dict[str, list[str]] = {}
+        self._current = ""
+
+        class_urls = {}
+        for module in self.modules:
+            for entry in module.entries:
+                if entry.kind == "class":
+                    class_urls[entry.name] = entry.url
+                    class_urls[entry.qualname] = entry.url
+        aliases, aliases_url = set(), ""
+        if project.type_aliases is not None:
+            aliases = annotations.module_aliases(f"{project.package}.{project.type_aliases}")
+            aliases_url = f"/doc/modules/{project.type_aliases}.html"
+        self.link_types = annotations.Linker(class_urls, aliases, aliases_url)
+        self.convert = markup.Converter(self._resolve)
+
+    def _resolve(self, name: str) -> str:
+        entries = self.index.get(name, [])
+        if len(entries) == 1:
+            return entries[0].url
+        if not entries:
+            self.errors.append(f"{self._current}: unknown reference [`{name}`]")
+        else:
+            options = ", ".join(e.qualname for e in entries)
+            self.errors.append(f"{self._current}: ambiguous reference [`{name}`], use one of {options}")
+        return "#"
+
+    def attributes(self, entry: collect.Entry) -> list[Attribute]:
+        """
+        :param entry: A class, namespace or enum.
+        :returns: The attributes listed on the page of the entry. These are the members of an enum, and the public
+         class attributes, annotated instance attributes (including `__slots__`) and properties of a class, sorted by
+         name. Types and descriptions are the annotations and the docstrings below the attributes in the class body
+         (or of its bases), and the return annotations and docstrings of the properties.
+        """
+        cls = entry.obj
+        source = annotations.class_attributes(cls)
+        if _is_enum(cls):
+            return [Attribute(m.name, m.value, description=source.get(m.name, (None, ""))[1]) for m in cls]
+
+        ret = []
+        for name, value in inspect.getmembers(cls):
+            if name.startswith("_") or inspect.isroutine(value):
+                continue
+            static = inspect.getattr_static(cls, name)
+            annotation, description = source.get(name, (None, ""))
+            if isinstance(static, property):
+                doc = docstring.parse(inspect.getdoc(static))
+                returns = annotations.source_annotations(static.fget)[1] if static.fget else None
+                desc = doc.description or (doc.returns.description if doc.returns else "")
+                ret.append(Attribute(name, type=returns, description=desc))
+            elif inspect.isdatadescriptor(static) or inspect.ismethoddescriptor(static):
+                if name in source:  # A slot of an annotated attribute, not a descriptor of a builtin base.
+                    ret.append(Attribute(name, type=annotation, description=description))
+            else:
+                ret.append(Attribute(name, value, annotation, description))
+        # Annotated instance attributes without a class attribute.
+        for name, (annotation, description) in source.items():
+            if annotation is not None and not name.startswith("_") and not hasattr(cls, name):
+                ret.append(Attribute(name, type=annotation, description=description))
+        return sorted(ret, key=lambda a: a.name)
+
+    def format_value(self, value: Any) -> str:
+        """
+        :param value: A default value of a parameter or the value of an attribute.
+        :returns: The HTML of the value. Parts are colored with the classes string, bool, num, class and func
+         inside a `default_value` span.
+        """
+        if isinstance(value, enum.Enum):
+            return (
+                f'<span class="default_value"><span class="class">{html.escape(type(value).__name__)}</span>.'
+                f'<span class="func">{html.escape(value.name)}</span></span>'
+            )
+        text, color_class = _default(value)
+        return f'<span class="default_value{" " + color_class if color_class else ""}">{text}</span>'
+
+    def page(self, entry: collect.Entry) -> str:
+        self._current = entry.qualname
+        is_namespace = entry.kind == "namespace" or _is_enum(entry.obj)
+        is_class = entry.kind in ("class", "namespace")
+        path, start, stop = collect.source_location(self.project, entry.obj)
+        source = dict(path=path, start=start, stop=stop, branch=self.project.branch)
+        if entry.kind == "method":
+            prename, classname = entry.owner.namespace, entry.owner.name  # type: ignore
+        else:
+            prename, classname = entry.namespace, ""
+        context: dict[str, Any] = dict(
+            title=entry.qualname,
+            prename=prename,
+            classname=classname,
+            name=entry.name,
+            is_class=is_class,
+            has_sig=False,
+            source=source,
+            sig=[],
+            attributes=[],
+            params=[],
+            returns=None,
+            raises=[],
+        )
+
+        # Namespaces and classes without their own __init__ or __new__ have no signature.
+        if is_namespace or (entry.kind == "class" and entry.func is None):
+            doc = docstring.parse(inspect.getdoc(entry.obj))
+            warnings = docstring.validate(doc, [], True)
+        else:
+            doc, warnings = self._signature(entry, context)
+        if is_class:
+            context["attributes"] = [
+                dict(
+                    name=a.name,
+                    type=self.link_types(a.type) if a.type else None,
+                    value=None if a.value is EMPTY else self.format_value(a.value),
+                    description=self.convert(a.description),
+                )
+                for a in self.attributes(entry)
+            ]
+        if warnings:
+            self.warnings[entry.qualname] = warnings
+        context["description"] = self.convert(doc.description)
+        context["raises"] = [dict(error=html.escape(err), description=self.convert(desc)) for err, desc in doc.raises]
+        return env.get_template("function.html").render(**context)
+
+    def _signature(self, entry: collect.Entry, context: dict[str, Any]) -> tuple[docstring.Docstring, list[str]]:
+        """
+        Add the signature, the parameters and the returns of a function, class or method to the page context.
+
+        :returns: (doc, warnings) The parsed docstring and the warnings about it.
+        """
+        func = entry.func
+        assert func is not None, "classes without __init__ or __new__ have no signature"
+        is_class = entry.kind == "class"
+        sig = inspect.signature(entry.obj)
+        params = [(n, p) for n, p in sig.parameters.items() if n != "self"]
+        context["has_sig"] = True
+
+        doc = docstring.parse((func.__doc__ or entry.obj.__doc__) if is_class else inspect.getdoc(func))
+        param_types, return_type = annotations.source_annotations(func)
+
+        for name, p in params:
+            star = {p.VAR_POSITIONAL: "*", p.VAR_KEYWORD: "**"}.get(p.kind, "")
+            default = None if p.default is p.empty else self.format_value(p.default)
+            context["sig"].append(dict(star=star, name=name, default=default))
+
+        context["params"] = [
+            dict(
+                name=name,
+                type=self.link_types(param_types[name]) if name in param_types else None,
+                description=self.convert(doc.params.get(name, "")),
+            )
+            for name, _ in params
+        ]
+
+        # Functions without a return value and without a returns description get no Returns section.
+        if not is_class and ((doc.returns and doc.returns.description) or return_type not in (None, "None")):
+            label, desc = (doc.returns.label, doc.returns.description) if doc.returns else ("out", "")
+            context["returns"] = dict(
+                label=label,
+                type=self.link_types(return_type) if return_type else None,
+                description=self.convert(desc),
+            )
+        # A __new__ returns the instance, so it may document ':returns:'.
+        no_returns = is_class and func.__name__ != "__new__"
+        return doc, docstring.validate(doc, [n for n, _ in params], no_returns)
+
+    def build(self) -> list[str]:
+        """
+        :returns: A list of errors.
+        """
+        functions_dir = os.path.join(self.project.docs, "doc", "functions")
+        nav_file = os.path.join(self.project.docs, "_includes", "api-nav.html")
+        if os.path.exists(functions_dir):
+            shutil.rmtree(functions_dir)
+        n = 0
+        for entry in collect.iter_pages(self.modules):
+            write(os.path.join(self.project.docs, entry.url.lstrip("/")), self.page(entry))
+            n += 1
+        write(nav_file, env.get_template("nav.html").render(package=self.project.package, modules=self.modules))
+        print(f"Wrote {n} API pages and {os.path.relpath(nav_file, self.project.root)}.")
+
+        if self.warnings:
+            print(f"\nDocstring warnings ({sum(len(w) for w in self.warnings.values())}):")
+            for name, warnings in self.warnings.items():
+                for w in warnings:
+                    print(f"  {name}: {w}")
+        return self.errors
+
+
+def dark_logo(svg: str) -> str:
+    """
+    :param svg: The SVG of the light logo.
+    :returns: The SVG of the dark logo, with the colors in `DARK_LOGO_COLORS` replaced.
+    """
+    pattern = re.compile("|".join(re.escape(c) for c in DARK_LOGO_COLORS), re.IGNORECASE)
+    return pattern.sub(lambda m: DARK_LOGO_COLORS[m.group(0).lower()], svg)
+
+
+def main(project: Project, builder: type[ApiBuilder] = ApiBuilder, argv: list[str] | None = None) -> None:
+    """
+    :param project: The documented project.
+    :param builder: The class that builds the API pages, a subclass of `ApiBuilder` for customizations.
+    :param argv: The command line arguments. Defaults to `sys.argv[1:]`.
+    """
+    parser = argparse.ArgumentParser(description=f"Generate the {project.package} website.")
+    parser.add_argument("target", nargs="?", default="all", choices=["api", "tutorials", "logo", "all"])
+    args = parser.parse_args(argv)
+    sys.path.insert(0, project.root)
+
+    errors = []
+    if args.target in ("api", "all"):
+        errors += builder(project).build()
+    if args.target in ("tutorials", "all"):
+        errors += tutorials.build(project, write)
+    if args.target in ("logo", "all"):
+        light = os.path.join(project.docs, project.logo)
+        dark = light.replace(".svg", "_dark.svg")
+        with open(light, encoding="utf-8") as f:
+            write(dark, dark_logo(f.read()))
+        print(f"Wrote {os.path.relpath(dark, project.root)}.")
+    if errors:
+        print(f"\nErrors ({len(errors)}):")
+        for e in errors:
+            print(f"  {e}")
+        sys.exit(1)