qdocs 0.2.0__tar.gz → 0.3.0__tar.gz

{qdocs-0.2.0 → qdocs-0.3.0}/.gitignore

@@ -6,3 +6,6 @@ _site/
 .jekyll-cache/
 .jekyll-metadata
 .ruff_cache/
+.vscode/*
+!.vscode/settings.json
+!.vscode/launch.json

qdocs-0.3.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "files.eol": "\n",
+}

{qdocs-0.2.0 → qdocs-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qdocs
-Version: 0.2.0
+Version: 0.3.0
 Summary: The website theme and generator of qspec and qunits.
 Project-URL: source, https://github.com/patmlr/qdocs
 Project-URL: tracker, https://github.com/patmlr/qdocs/issues
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Documentation
 Classifier: Topic :: Software Development :: Documentation
 Requires-Python: >=3.12
+Requires-Dist: catppuccin[pygments]
 Requires-Dist: jinja2
 Requires-Dist: pygments>=2.17
 Description-Content-Type: text/markdown
@@ -45,6 +46,7 @@ The site provides `_data/navigation.yml` (top navigation), `_data/tutorials.yml`
 `_includes/badges.html` (optional) and its logos `assets/img/logo.svg`, `logo_dark.svg` and `logo_small.svg`.
 Any theme file can be overridden by a file at the same path in the site. Extra styles go in `_sass/custom.scss`,
 extra `<head>` tags in `_includes/head-custom.html`.
+The search in the top navigation finds the pages with a `title` in their front matter, by title and text.
 
 `docs/requirements.txt`, with the same version as `remote_theme`:
 
@@ -66,7 +68,6 @@ PROJECT = Project(
     modules=["algebra", "analyze", "models", "physics"],
     root=ROOT,
     namespaced={"analyze", "models"},  # qspec.models.Model instead of qspec.Model.
-    type_aliases="qtypes",  # Optional: link these type aliases in annotations to their module page.
 )
 
 if __name__ == "__main__":
@@ -79,20 +80,34 @@ python docs/_gen/build.py [api | tutorials | logo | all]
 
 | Target      | Source                                    | Output                                           |
 |-------------|-------------------------------------------|--------------------------------------------------|
-| `api`       | docstrings and signatures of the package  | `doc/functions/**`, `_includes/api-nav.html`     |
+| `api`       | docstrings and signatures of the package  | `doc/functions/**`, `_includes/api-nav.html`,    |
+|             |                                           | `_includes/types/<module>.html`                  |
 | `tutorials` | `# docs: <name>` regions in `examples/`   | `_includes/code/<name>.html`                     |
 | `logo`      | `assets/img/logo.svg`                     | `assets/img/logo_dark.svg`                       |
 
 The module pages `doc/modules/<module>.html` and the overview `doc/doc.html` are written by hand with the `api`
 layout, which adds the navigation. See `Project` in [`qdocs/project.py`](qdocs/project.py) for all options.
 
+The type aliases of a module (`type scalar = int | float`) are listed in `_includes/types/<module>.html`. Include the
+list in the module page with `{% include types/<module>.html %}`. Type aliases in annotations link to their entry in
+that list, and the build notes module pages that do not include their list.
+
 ### Customizations
 
 Every class page has an Attributes section with the public class attributes, the annotated instance attributes
-(including `__slots__`) and the properties of the class. Classes listed in `Project.namespaces` are documented like a
-module of constants: no signature and no methods, only the description and the attributes. Enums are documented this
-way automatically. Subclass `ApiBuilder` to change which attributes are listed (`attributes` returns a list of
-`Attribute`) or how values are shown:
+(including `__slots__`) and the properties of the class, sorted by name. Classes listed in `Project.namespaces` are
+documented like a module of constants: no signature and no methods, only the description and the attributes in source
+order. Enums are documented this way automatically.
+
+Default values in signatures and attribute values are shown as Python source:
+
+- Strings, numbers, booleans, enum members, classes and functions as written in code. Documented classes are linked.
+- Tuples, lists, sets and dicts item by item. Sets are sorted, so the pages do not change between builds.
+- Other objects as the call of their class that recreates them, e.g. `Unit(1000.0, frozenset({('km', 1)}), Length,
+  Context.I)`, if every parameter of the class is an attribute of the object, otherwise as `str(value)`.
+
+Subclass `ApiBuilder` to change which attributes are listed (`attributes` returns a list of `Attribute`) or how
+values are shown:
 
 ```python
 from qdocs import ApiBuilder, Project, main
@@ -101,15 +116,15 @@ from qdocs import ApiBuilder, Project, main
 class Builder(ApiBuilder):
     def format_value(self, value) -> str:
         if isinstance(value, Unit):
-            return f'<span class="default_value"><span class="class">Unit</span>(...)</span>'
+            return f'<span class="class">Unit</span>({self.format_value(value.scale)})'
         return super().format_value(value)
 
 
 main(PROJECT, Builder)
 ```
 
-`format_value` is used for default values in signatures and for attribute values. Color the parts of a value with
-the classes `string`, `bool`, `num`, `class` and `func` inside a `default_value` span.
+`format_value` returns the HTML of a value or of a part of a value, and is called for the items of containers and
+the arguments of objects, too. Color the parts with the classes `string`, `bool`, `num`, `class` and `func`.
 
 ## Docstrings
 
@@ -136,21 +151,30 @@ def york_fit(x, y, sigma_x=None, ...):
 
 - `` `code` `` and raw HTML (e.g. links to papers) are passed through.
 - `$inline$` and `$$block$$` math is rendered by MathJax. Block math always stands on its own line on the website.
-- `` [`name`] `` links to a documented object: `fit`, `King.fit`, `qspec.models.fit`, `qspec.physics.doppler`
-  or a module such as `qspec.analyze`. Unknown or ambiguous names stop the build.
+- `` [`name`] `` links to a documented object: `fit`, `King.fit`, `qspec.models.fit`, `qspec.physics.doppler`,
+  a module such as `qspec.analyze` or a type alias such as `scalar`. Unknown or ambiguous names stop the build.
 - Blank lines separate paragraphs, lines starting with `- ` form a list.
 - A leading `(name)` in `:returns:` labels the return value(s), otherwise it is shown as `out`.
 - Types are taken from the annotations as written in the source.
 - Methods without a docstring inherit the docstring of the overridden method.
 - The signature and the parameters of a class are those of `__init__`, or of `__new__` if only that is overridden.
   A class that overrides neither has no signature.
+- The description of a class is its docstring, followed by the description in the docstring of `__init__` or
+  `__new__`. The fields can be in either docstring.
+- Type aliases are described by a string on the line right below them (a string after a blank line is not taken):
+
+  ```python
+  type ExpMap = frozenset[tuple[str, int]]
+  """An exponent map, a frozenset of (symbol, exponent) pairs."""
+  ```
+
 - Attributes are described by a string below their assignment or annotation in the class body, properties by their
   docstring:
 
   ```python
   class Unit:
       scale: float
-      """The scale factor of the unit relative to the SI base units."""
+      """The scale factor of the unit relative to the SI unit of its dimension."""
   ```
 
 The generator warns about parameters that are missing in the docstring or the signature.

{qdocs-0.2.0 → qdocs-0.3.0}/README.md

@@ -27,6 +27,7 @@ The site provides `_data/navigation.yml` (top navigation), `_data/tutorials.yml`
 `_includes/badges.html` (optional) and its logos `assets/img/logo.svg`, `logo_dark.svg` and `logo_small.svg`.
 Any theme file can be overridden by a file at the same path in the site. Extra styles go in `_sass/custom.scss`,
 extra `<head>` tags in `_includes/head-custom.html`.
+The search in the top navigation finds the pages with a `title` in their front matter, by title and text.
 
 `docs/requirements.txt`, with the same version as `remote_theme`:
 
@@ -48,7 +49,6 @@ PROJECT = Project(
     modules=["algebra", "analyze", "models", "physics"],
     root=ROOT,
     namespaced={"analyze", "models"},  # qspec.models.Model instead of qspec.Model.
-    type_aliases="qtypes",  # Optional: link these type aliases in annotations to their module page.
 )
 
 if __name__ == "__main__":
@@ -61,20 +61,34 @@ python docs/_gen/build.py [api | tutorials | logo | all]
 
 | Target      | Source                                    | Output                                           |
 |-------------|-------------------------------------------|--------------------------------------------------|
-| `api`       | docstrings and signatures of the package  | `doc/functions/**`, `_includes/api-nav.html`     |
+| `api`       | docstrings and signatures of the package  | `doc/functions/**`, `_includes/api-nav.html`,    |
+|             |                                           | `_includes/types/<module>.html`                  |
 | `tutorials` | `# docs: <name>` regions in `examples/`   | `_includes/code/<name>.html`                     |
 | `logo`      | `assets/img/logo.svg`                     | `assets/img/logo_dark.svg`                       |
 
 The module pages `doc/modules/<module>.html` and the overview `doc/doc.html` are written by hand with the `api`
 layout, which adds the navigation. See `Project` in [`qdocs/project.py`](qdocs/project.py) for all options.
 
+The type aliases of a module (`type scalar = int | float`) are listed in `_includes/types/<module>.html`. Include the
+list in the module page with `{% include types/<module>.html %}`. Type aliases in annotations link to their entry in
+that list, and the build notes module pages that do not include their list.
+
 ### Customizations
 
 Every class page has an Attributes section with the public class attributes, the annotated instance attributes
-(including `__slots__`) and the properties of the class. Classes listed in `Project.namespaces` are documented like a
-module of constants: no signature and no methods, only the description and the attributes. Enums are documented this
-way automatically. Subclass `ApiBuilder` to change which attributes are listed (`attributes` returns a list of
-`Attribute`) or how values are shown:
+(including `__slots__`) and the properties of the class, sorted by name. Classes listed in `Project.namespaces` are
+documented like a module of constants: no signature and no methods, only the description and the attributes in source
+order. Enums are documented this way automatically.
+
+Default values in signatures and attribute values are shown as Python source:
+
+- Strings, numbers, booleans, enum members, classes and functions as written in code. Documented classes are linked.
+- Tuples, lists, sets and dicts item by item. Sets are sorted, so the pages do not change between builds.
+- Other objects as the call of their class that recreates them, e.g. `Unit(1000.0, frozenset({('km', 1)}), Length,
+  Context.I)`, if every parameter of the class is an attribute of the object, otherwise as `str(value)`.
+
+Subclass `ApiBuilder` to change which attributes are listed (`attributes` returns a list of `Attribute`) or how
+values are shown:
 
 ```python
 from qdocs import ApiBuilder, Project, main
@@ -83,15 +97,15 @@ from qdocs import ApiBuilder, Project, main
 class Builder(ApiBuilder):
     def format_value(self, value) -> str:
         if isinstance(value, Unit):
-            return f'<span class="default_value"><span class="class">Unit</span>(...)</span>'
+            return f'<span class="class">Unit</span>({self.format_value(value.scale)})'
         return super().format_value(value)
 
 
 main(PROJECT, Builder)
 ```
 
-`format_value` is used for default values in signatures and for attribute values. Color the parts of a value with
-the classes `string`, `bool`, `num`, `class` and `func` inside a `default_value` span.
+`format_value` returns the HTML of a value or of a part of a value, and is called for the items of containers and
+the arguments of objects, too. Color the parts with the classes `string`, `bool`, `num`, `class` and `func`.
 
 ## Docstrings
 
@@ -118,21 +132,30 @@ def york_fit(x, y, sigma_x=None, ...):
 
 - `` `code` `` and raw HTML (e.g. links to papers) are passed through.
 - `$inline$` and `$$block$$` math is rendered by MathJax. Block math always stands on its own line on the website.
-- `` [`name`] `` links to a documented object: `fit`, `King.fit`, `qspec.models.fit`, `qspec.physics.doppler`
-  or a module such as `qspec.analyze`. Unknown or ambiguous names stop the build.
+- `` [`name`] `` links to a documented object: `fit`, `King.fit`, `qspec.models.fit`, `qspec.physics.doppler`,
+  a module such as `qspec.analyze` or a type alias such as `scalar`. Unknown or ambiguous names stop the build.
 - Blank lines separate paragraphs, lines starting with `- ` form a list.
 - A leading `(name)` in `:returns:` labels the return value(s), otherwise it is shown as `out`.
 - Types are taken from the annotations as written in the source.
 - Methods without a docstring inherit the docstring of the overridden method.
 - The signature and the parameters of a class are those of `__init__`, or of `__new__` if only that is overridden.
   A class that overrides neither has no signature.
+- The description of a class is its docstring, followed by the description in the docstring of `__init__` or
+  `__new__`. The fields can be in either docstring.
+- Type aliases are described by a string on the line right below them (a string after a blank line is not taken):
+
+  ```python
+  type ExpMap = frozenset[tuple[str, int]]
+  """An exponent map, a frozenset of (symbol, exponent) pairs."""
+  ```
+
 - Attributes are described by a string below their assignment or annotation in the class body, properties by their
   docstring:
 
   ```python
   class Unit:
       scale: float
-      """The scale factor of the unit relative to the SI base units."""
+      """The scale factor of the unit relative to the SI unit of its dimension."""
   ```
 
 The generator warns about parameters that are missing in the docstring or the signature.

{qdocs-0.2.0 → qdocs-0.3.0}/pyproject.toml

@@ -20,6 +20,7 @@ classifiers = [
     "Topic :: Software Development :: Documentation",
 ]
 dependencies = [
+    "catppuccin[pygments]",
     "jinja2",
     "pygments>=2.17",
 ]

{qdocs-0.2.0 → qdocs-0.3.0}/qdocs/annotations.py

@@ -14,21 +14,30 @@ from typing import Any
 IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_.]*")
 
 
-def module_aliases(module: str) -> set[str]:
+def type_aliases(module: str) -> list[tuple[str, str, str, str]]:
     """
-    :param module: The fully qualified name of a module.
-    :returns: The type aliases (`type x = ...`, `x = ...`) and classes defined in the module.
+    :param module: The fully qualified name of a module. The aliases of a package are those in its `__init__.py`.
+    :returns: (name, params, value, description) The public type aliases (`type name[params] = value`) of the module
+     in source order, with their type parameters ("" if there are none) and the docstring on the line right below
+     the alias ("" if there is none).
     """
-    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__"}
+    source = inspect.getsource(importlib.import_module(module))
+    tree = ast.parse(source)
+    ret = []
+    for node, after in zip(tree.body, [*tree.body[1:], None]):
+        if not isinstance(node, ast.TypeAlias) or node.name.id.startswith("_"):
+            continue
+        params = ", ".join(ast.get_source_segment(source, p) for p in node.type_params)  # type: ignore
+        doc = ""
+        if (
+            isinstance(after, ast.Expr)
+            and isinstance(getattr(after.value, "value", None), str)
+            and after.lineno == node.end_lineno + 1  # type: ignore
+        ):
+            doc = inspect.cleandoc(after.value.value)  # type: ignore
+        value = ast.get_source_segment(source, node.value)
+        ret.append((node.name.id, f"[{params}]" if params else "", value, doc))  # type: ignore
+    return ret
 
 
 def _strip_quotes(text: str) -> str:
@@ -109,19 +118,19 @@ def _fallback(func: Callable[..., Any]) -> tuple[dict[str, str], str | None]:
 
 
 class Linker:
-    def __init__(self, class_urls: dict[str, str], aliases: set[str] = frozenset(), aliases_url: str = "") -> None:  # type: ignore
+    def __init__(self, class_urls: dict[str, str], alias_urls: dict[str, dict[str, str]]) -> None:
         """
         :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.
+        :param alias_urls: A map from type alias names to the site urls of their definitions, by defining module.
         """
         self.class_urls = class_urls
-        self.aliases = aliases
-        self.aliases_url = aliases_url
+        self.alias_urls = alias_urls
 
-    def __call__(self, annotation: str) -> str:
+    def __call__(self, annotation: str, module: str | None = None) -> str:
         """
         :param annotation: The annotation source text.
+        :param module: The module of the annotation. Its own type aliases take precedence over those of the other
+         modules. A type alias defined in several other modules is not linked.
         :returns: The HTML of the annotation with documented classes and type aliases linked.
         """
         out = []
@@ -129,8 +138,9 @@ class Linker:
         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 and name in self.alias_urls:
+                urls = self.alias_urls[name]
+                url = urls.get(module) or (next(iter(urls.values())) if len(urls) == 1 else None)  # type: ignore
             if url is None:
                 continue
             out.append(html.escape(annotation[last : m.start()]))

{qdocs-0.2.0 → qdocs-0.3.0}/qdocs/build.py

@@ -12,6 +12,7 @@ import argparse
 import enum
 import html
 import inspect
+import numbers
 import os
 import re
 import shutil
@@ -40,6 +41,8 @@ env = Environment(
 # The colors of the light logo and their replacements in the dark logo.
 DARK_LOGO_COLORS = {"#000000": "#e8e6ed", "#808080": "#a9a6b0"}
 
+TYPES_INCLUDE = re.compile(r"{%\s*include\s+types/(\S+?)\.html\s*%}")
+
 # The value of an attribute that has none on the class, e.g. an instance attribute or a property.
 EMPTY = inspect.Parameter.empty
 
@@ -60,19 +63,27 @@ def write(path: str, text: str) -> None:
         f.write(text)
 
 
-def _default(value: Any) -> tuple[str, str]:
+def _ctor_args(value: Any) -> list[tuple[str | None, Any]] | None:
     """
-    :returns: (text, color_class) The HTML text of a default value and the CSS class that colors it.
+    :param value: An object.
+    :returns: The arguments that recreate the object with its class, as (keyword, value) pairs. The keyword is `None`
+     for positional arguments. `None` if the class takes no arguments, `*args` or `**kwargs`, or if a parameter is not
+     an attribute of the object.
     """
-    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)), ""
+    try:
+        params = list(inspect.signature(type(value)).parameters.values())
+    except (TypeError, ValueError):
+        return None
+    if not params or any(p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD) for p in params):
+        return None
+    args = []
+    for p in params:
+        try:
+            arg = getattr(value, p.name)
+        except Exception:
+            return None
+        args.append((p.name if p.kind == p.KEYWORD_ONLY else None, arg))
+    return args
 
 
 def _is_enum(obj: Any) -> bool:
@@ -99,12 +110,19 @@ class ApiBuilder:
                 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)
+        alias_urls: dict[str, dict[str, str]] = {}
+        for module in self.modules:
+            for alias in module.aliases:
+                alias_urls.setdefault(alias.name, {})[module.name] = alias.url
+        self.link_types = annotations.Linker(class_urls, alias_urls)
         self.convert = markup.Converter(self._resolve)
+        self._class_urls = {
+            entry.obj: entry.url
+            for module in self.modules
+            for entry in module.entries
+            if entry.kind in ("class", "namespace")
+        }
+        self._formatting: set[int] = set()
 
     def _resolve(self, name: str) -> str:
         entries = self.index.get(name, [])
@@ -122,8 +140,9 @@ class ApiBuilder:
         :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.
+         name. Enums and namespaces keep the source order. 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)
@@ -150,21 +169,73 @@ class ApiBuilder:
         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)
+        ret.sort(key=lambda a: a.name)
+        if entry.kind == "namespace":
+            order: dict[str, int] = {}
+            for name in [*source, *(n for c in reversed(cls.__mro__) for n in vars(c))]:
+                order.setdefault(name, len(order))
+            ret.sort(key=lambda a: order.get(a.name, len(order)))
+        return ret
 
     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.
+        :param value: A default value of a parameter, the value of an attribute or a part of such a value.
+        :returns: The HTML of the value, with its parts colored by the classes string, bool, num, class and func.
+         Tuples, lists, sets and dicts are formatted item by item, sets sorted. Other objects are shown as the call
+         of their class that recreates them, e.g. `Unit(1000.0, frozenset({('km', 1)}), Length, Context.I)`, if all
+         parameters of the class are attributes of the object, otherwise as `str(value)`. Documented classes are
+         linked to their pages.
         """
         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>'
+            return f'{self._class(type(value))}.<span class="func">{html.escape(value.name)}</span>'
+        if isinstance(value, bool):
+            return f'<span class="bool">{value}</span>'
+        if isinstance(value, str):
+            return f'<span class="string">{html.escape(repr(value))}</span>'  # Quotes and escapes as in the source.
+        if isinstance(value, numbers.Number):
+            return f'<span class="num">{html.escape(str(value))}</span>'
+        if value is None:
+            return "None"
+        if inspect.isclass(value):
+            return self._class(value)
+        if inspect.isroutine(value):
+            return f'<span class="func">{html.escape(value.__name__)}</span>'
+        if id(value) in self._formatting:
+            return "..."
+        self._formatting.add(id(value))
+        try:
+            return self._format_object(value)
+        finally:
+            self._formatting.discard(id(value))
+
+    def _format_object(self, value: Any) -> str:
+        cls = type(value)
+        if cls is tuple:
+            items = [self.format_value(v) for v in value]
+            return f"({', '.join(items)}{',' if len(items) == 1 else ''})"
+        if cls is list:
+            return f"[{', '.join(self.format_value(v) for v in value)}]"
+        if cls is dict:
+            return f"{{{', '.join(f'{self.format_value(k)}: {self.format_value(v)}' for k, v in value.items())}}}"
+        if cls in (set, frozenset):
+            items = sorted(self.format_value(v) for v in value)
+            if not items:
+                return f"{self._class(cls)}()"
+            braced = f"{{{', '.join(items)}}}"
+            return braced if cls is set else f"{self._class(cls)}({braced})"
+        args = _ctor_args(value)
+        if args is None:
+            return html.escape(str(value))
+        parts = [(f"{keyword}=" if keyword else "") + self.format_value(arg) for keyword, arg in args]
+        return f"{self._class(cls)}({', '.join(parts)})"
+
+    def _class(self, cls: type) -> str:
+        name = f'<span class="class">{html.escape(cls.__name__)}</span>'
+        url = self._class_urls.get(cls)
+        return name if url is None else f"<a href=\"{{{{ '{url}' | relative_url }}}}\">{name}</a>"
+
+    def _value(self, value: Any) -> str:
+        return f'<span class="default_value">{self.format_value(value)}</span>'
 
     def page(self, entry: collect.Entry) -> str:
         self._current = entry.qualname
@@ -201,8 +272,8 @@ class ApiBuilder:
             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),
+                    type=self.link_types(a.type, entry.module) if a.type else None,
+                    value=None if a.value is EMPTY else self._value(a.value),
                     description=self.convert(a.description),
                 )
                 for a in self.attributes(entry)
@@ -226,18 +297,21 @@ class ApiBuilder:
         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))
+        if is_class:
+            doc = docstring.merge(docstring.parse(entry.obj.__doc__), docstring.parse(func.__doc__))
+        else:
+            doc = docstring.parse(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)
+            default = None if p.default is p.empty else self._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,
+                type=self.link_types(param_types[name], entry.module) if name in param_types else None,
                 description=self.convert(doc.params.get(name, "")),
             )
             for name, _ in params
@@ -248,7 +322,7 @@ class ApiBuilder:
             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,
+                type=self.link_types(return_type, entry.module) if return_type else None,
                 description=self.convert(desc),
             )
         # A __new__ returns the instance, so it may document ':returns:'.
@@ -269,6 +343,7 @@ class ApiBuilder:
             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)}.")
+        self._write_types()
 
         if self.warnings:
             print(f"\nDocstring warnings ({sum(len(w) for w in self.warnings.values())}):")
@@ -277,6 +352,50 @@ class ApiBuilder:
                     print(f"  {name}: {w}")
         return self.errors
 
+    def types(self, module: collect.Module) -> str:
+        """
+        :param module: A module with type aliases.
+        :returns: The HTML of the list of the type aliases of the module, included by its module page.
+        """
+        self._current = f"{self.project.package}.{module.name}"
+        aliases = [
+            dict(
+                name=a.name,
+                params=html.escape(a.params),
+                value=self.link_types(a.value, module.name),
+                description=self.convert(a.description),
+            )
+            for a in module.aliases
+        ]
+        return env.get_template("types.html").render(aliases=aliases)
+
+    def _write_types(self) -> None:
+        """
+        Write the type alias lists `_includes/types/<module>.html` and check that the module pages include them.
+        """
+        types_dir = os.path.join(self.project.docs, "_includes", "types")
+        if os.path.exists(types_dir):
+            shutil.rmtree(types_dir)
+        with_aliases = {m.name for m in self.modules if m.aliases}
+        for module in self.modules:
+            if module.aliases:
+                write(os.path.join(types_dir, f"{module.name}.html"), self.types(module))
+        if with_aliases:
+            print(f"Wrote the type alias lists of {', '.join(sorted(with_aliases))} to _includes/types/.")
+
+        for module in self.modules:
+            page = os.path.join(self.project.docs, module.url.lstrip("/"))
+            text = ""
+            if os.path.exists(page):
+                with open(page, encoding="utf-8") as f:
+                    text = f.read()
+            included = set(TYPES_INCLUDE.findall(text))
+            path = os.path.relpath(page, self.project.root)
+            if module.name in with_aliases and module.name not in included:
+                print(f"  note: {path} does not include types/{module.name}.html, its type aliases are not listed")
+            for name in sorted(included - with_aliases):
+                self.errors.append(f"{path}: includes types/{name}.html, but module '{name}' has no type aliases")
+
 
 def dark_logo(svg: str) -> str:
     """

{qdocs-0.2.0 → qdocs-0.3.0}/qdocs/collect.py

@@ -10,6 +10,7 @@ from collections.abc import Callable, Iterator
 from dataclasses import dataclass, field
 from typing import Any
 
+from qdocs import annotations
 from qdocs.project import Project
 
 
@@ -18,11 +19,11 @@ class Entry:
     """A documented function, class, namespace or method."""
 
     name: str
-    obj: Any  # The function, class or method. None for modules.
+    obj: Any  # The function, class or method. None for modules and aliases.
     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).
+    kind: str  # "function", "class", "namespace", "method", or "module" and "alias" (only reference targets).
     owner: "Entry | None" = None  # The class of a method.
     methods: list["Method"] = field(default_factory=list)  # The methods of a class.
 
@@ -34,13 +35,13 @@ class Entry:
     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 only that is overridden. None for a class that overrides neither, or only by `typing`, e.g. a `Protocol`.
         """
         if self.kind != "class":
             return self.obj
         for name in ("__init__", "__new__"):
             func = getattr(self.obj, name)
-            if func is not getattr(object, name):
+            if func is not getattr(object, name) and getattr(func, "__module__", None) != "typing":
                 return func
         return None
 
@@ -54,11 +55,27 @@ class Method:
     inherited_from: Entry | None = None  # The documented class the method is inherited from.
 
 
+@dataclass
+class Alias:
+    """
+    A type alias `type name[params] = value`, listed on the page of its module. `params` is the source text of the
+    type parameters, e.g. "[T: generic]", or "", `value` the source text of the aliased type and `url` the anchor on
+    the module page, e.g. "/doc/modules/prefix.html#ExpMap".
+    """
+
+    name: str
+    params: str
+    value: str
+    description: str
+    url: str
+
+
 @dataclass
 class Module:
     name: str
     url: str
     entries: list[Entry]
+    aliases: list[Alias] = field(default_factory=list)
 
 
 def _public_methods(cls: type) -> list[str]:
@@ -96,7 +113,12 @@ def collect(project: Project) -> list[Module]:
             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))
+        url = f"/doc/modules/{file}.html"
+        aliases = [
+            Alias(name, params, value, description, f"{url}#{name}")
+            for name, params, value, description in annotations.type_aliases(f"{project.package}.{file}")
+        ]
+        modules.append(Module(file, url, entries, aliases))
 
     # Methods are resolved after all classes are known, so inherited methods can link across modules.
     for cls, entry in classes.items():
@@ -133,7 +155,7 @@ def build_index(project: Project, modules: list[Module]) -> dict[str, list[Entry
     :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`).
+     the module names (`qspec.analyze`) and the type aliases (`scalar`, `qspec.qtypes.scalar`).
     """
     index: dict[str, list[Entry]] = {}
     package = project.package
@@ -152,6 +174,10 @@ def build_index(project: Project, modules: list[Module]) -> dict[str, list[Entry
             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 alias in module.aliases:
+            entry = Entry(alias.name, None, module.name, f"{package}.{module.name}", alias.url, "alias")
+            add(alias.name, entry)
+            add(entry.qualname, entry)
         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)

{qdocs-0.2.0 → qdocs-0.3.0}/qdocs/docstring.py

@@ -89,6 +89,25 @@ def parse(doc: str | None) -> Docstring:
     return ret
 
 
+def merge(first: Docstring, second: Docstring) -> Docstring:
+    """
+    :param first: A parsed docstring, e.g. of a class.
+    :param second: A parsed docstring that adds to the first, e.g. of its `__init__`.
+    :returns: The descriptions of both, separated by a blank line, and their fields. The fields of `second` override
+     those of `first`.
+    """
+    descriptions = [first.description, second.description]
+    if first.description == second.description:
+        descriptions = [first.description]
+    return Docstring(
+        description="\n\n".join(d for d in descriptions if d),
+        params={**first.params, **second.params},
+        returns=second.returns or first.returns,
+        raises=[*first.raises, *second.raises],
+        warnings=[*first.warnings, *second.warnings],
+    )
+
+
 def validate(doc: Docstring, params: list[str], is_class: bool) -> list[str]:
     """
     :param doc: The parsed docstring.

{qdocs-0.2.0 → qdocs-0.3.0}/qdocs/project.py

@@ -19,7 +19,6 @@ class Project:
     :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`.
@@ -32,7 +31,6 @@ class Project:
     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 = ""

qdocs-0.3.0/qdocs/templates/types.html

@@ -0,0 +1,13 @@
+<dl class="field-list">
+<dt class="field-head">Type aliases<span class="colon">:</span></dt>
+<dd class="field-par">
+<dl>
+[%- for a in aliases %]
+<dt id="[[ a.name ]]">[[ a.name ]][[ a.params ]]<span class="attr-value"><em>[[ a.value ]]</em></span></dt>
+[%- if a.description %]
+<dd class="field-desc">[[ a.description ]]</dd>
+[%- endif %]
+[%- endfor %]
+</dl>
+</dd>
+</dl>