gri-plot 0.2.6__tar.gz → 0.2.7__tar.gz

gri_plot-0.2.7/.gen_api_summary.py

@@ -0,0 +1,592 @@
+# ruff: noqa: T201
+"""Generate <package>/docs/api_summary.md from the package's public API.
+
+The summary ships inside the wheel so that a reader with only the installed
+package -- no repository, no web -- can see every public name, its signature,
+and the first line of its docstring in one file. `help(name)` has the rest.
+
+The public API is the package's `__all__` (or, without one, the non-underscore
+names its `__init__.py` defines or imports from inside the package). Each name
+is traced through the re-export chain to the statement that defines it, and
+listed under the module that exports it -- the path to import it from. An
+exported submodule is expanded the same way, so a package whose API is a set of
+subpackages (`from pkg.conversion import ...`) is covered too.
+
+Everything is read with `ast`; nothing is imported. That keeps the script
+dependency-free (it runs before the package's own dependencies are installed)
+and free of import side effects.
+
+Output is deterministic -- no dates or versions -- so a regenerated file only
+differs when the API does, and `--check` can be used as a staleness gate. A
+package without a docs/ directory is skipped, so the script (distributed to
+every repo) is inert until a repo's docs are set up.
+
+Usage:
+    python .gen_api_summary.py           # rewrite docs/api_summary.md if stale
+    python .gen_api_summary.py --check   # exit 1 if stale, write nothing
+    python .gen_api_summary.py --root ../gri-pos   # another repo
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+SUMMARY_NAME = "api_summary.md"
+# Re-export chains deeper than this are treated as unresolvable (and cycles).
+MAX_IMPORT_DEPTH = 10
+
+# Dunder methods rendered as the operator or builtin they enable, in this order.
+OPERATORS = {
+    "__add__": "+",
+    "__sub__": "-",
+    "__mul__": "*",
+    "__matmul__": "@",
+    "__truediv__": "/",
+    "__floordiv__": "//",
+    "__mod__": "%",
+    "__pow__": "**",
+    "__neg__": "unary -",
+    "__abs__": "abs()",
+    "__eq__": "==",
+    "__lt__": "<",
+    "__le__": "<=",
+    "__gt__": ">",
+    "__ge__": ">=",
+    "__len__": "len()",
+    "__iter__": "iter()",
+    "__getitem__": "[]",
+    "__contains__": "in",
+    "__hash__": "hash()",
+    "__enter__": "with",
+}
+ORDERING_OPS = ("<", "<=", ">", ">=")
+# Dunders that are public API in their own right and listed as methods.
+LISTED_DUNDERS = ("__call__",)
+ENUM_BASES = {"Enum", "IntEnum", "StrEnum", "Flag", "IntFlag"}
+# Class-level assignments that declare typing machinery, not data fields.
+TYPING_FACTORIES = {"TypeVar", "TypeVarTuple", "ParamSpec", "NewType"}
+# Longest constant value shown inline; anything longer is elided.
+MAX_VALUE_LEN = 60
+
+type _Def = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+@dataclass
+class Entry:
+    """One public name, resolved to the node that defines it.
+
+    Attributes:
+        name: The name as exported.
+        path: File of the module that defines it (or of the module itself, for
+            an exported submodule).
+        exporter: File of the module whose public names include it.
+        node: The defining statement, or None if it was not found.
+        doc: Attribute docstring of a constant, if any.
+        origin: Import source when the name comes from outside the package.
+        is_module: True when the name is a submodule rather than an object.
+    """
+
+    name: str
+    path: Path
+    node: ast.stmt | None
+    doc: str | None = None
+    origin: str | None = None
+    is_module: bool = False
+    exporter: Path | None = None
+
+
+@dataclass
+class _Walk:
+    """Parse cache and traversal state for one package."""
+
+    pkg_dir: Path
+    trees: dict[Path, ast.Module] = field(default_factory=dict)
+    expanded: set[Path] = field(default_factory=set)
+    listed: set[tuple[Path, str]] = field(default_factory=set)
+
+    def parse(self, path: Path) -> ast.Module:
+        if path not in self.trees:
+            self.trees[path] = ast.parse(path.read_text(), filename=str(path))
+        return self.trees[path]
+
+
+def main() -> None:
+    """Write or check the package's docs/api_summary.md."""
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="exit 1 if the summary is stale instead of rewriting it",
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=ROOT,
+        help="repository root (default: the directory holding this script)",
+    )
+    args = parser.parse_args()
+
+    root = args.root.resolve()
+    dist_name, pkg_dir = _find_package(root)
+    if not (pkg_dir / "docs").is_dir():
+        # This script ships to every repo from py-common, including ones whose
+        # docs/ has not been set up yet; the summary starts once docs/ exists.
+        print(f"{pkg_dir.name}/docs/ does not exist; no API summary to maintain.")
+        return
+    text = render_summary(dist_name, pkg_dir)
+    out = pkg_dir / "docs" / SUMMARY_NAME
+    current = out.read_text() if out.exists() else None
+    if current == text:
+        return
+    rel = out.relative_to(root)
+    if args.check:
+        print(f"{rel} is stale; run `python .gen_api_summary.py` and commit it.")
+        sys.exit(1)
+    out.parent.mkdir(exist_ok=True)
+    out.write_text(text)
+    print(f"Updated {rel}")
+
+
+def render_summary(dist_name: str, pkg_dir: Path) -> str:
+    """Render the summary markdown for one package.
+
+    Args:
+        dist_name: Distribution name, eg "gri-nsepoch".
+        pkg_dir: Directory of the top-level import package.
+
+    Returns:
+        The full markdown text, ending in a single newline.
+    """
+    walk = _Walk(pkg_dir)
+    init = pkg_dir / "__init__.py"
+    walk.expanded.add(init)
+    entries = _public_entries(init, walk)
+    lines = [
+        f"# {dist_name} API summary",
+        "",
+        "Generated from the source by `.gen_api_summary.py`; do not edit by hand.",
+        f"Lists every public name exported by `{pkg_dir.name}`, under the module",
+        "to import it from, with its signature and the first line of its",
+        "docstring. `help(name)` shows the full docstring and examples.",
+    ]
+    sections: dict[Path, list[Entry]] = {}
+    for entry in entries:
+        sections.setdefault(entry.exporter or entry.path, []).append(entry)
+    for path, group in sections.items():
+        lines += ["", f"## {_module_name(path, pkg_dir)}"]
+        lines += _summary_block(_first_paragraph(ast.get_docstring(walk.parse(path))))
+        constants = [e for e in group if _is_constant(e)]
+        if constants:
+            lines += ["", "### Constants", ""]
+            lines += [_constant_line(e) for e in constants]
+        for entry in group:
+            if not _is_constant(entry):
+                lines += ["", *_render_entry(entry)]
+    return "\n".join(lines) + "\n"
+
+
+def _find_package(root: Path) -> tuple[str, Path]:
+    """Return the distribution name and import package directory."""
+    with (root / "pyproject.toml").open("rb") as fp:
+        dist_name = tomllib.load(fp)["project"]["name"]
+    pkg_dir = root / dist_name.replace("-", "_")
+    if not (pkg_dir / "__init__.py").is_file():
+        raise SystemExit(f"No package at {pkg_dir}")
+    return dist_name, pkg_dir
+
+
+def _public_entries(path: Path, walk: _Walk) -> list[Entry]:
+    """Resolve a module's public names, expanding exported submodules."""
+    entries: list[Entry] = []
+    for name in _public_names(path, walk):
+        entry = _resolve(path, name, walk)
+        entry.exporter = path
+        if not entry.is_module:
+            # A name re-exported by two public modules is listed once, under the
+            # first (shallowest) module that exports it.
+            if (entry.path, name) not in walk.listed:
+                walk.listed.add((entry.path, name))
+                entries.append(entry)
+        elif entry.path not in walk.expanded:
+            walk.expanded.add(entry.path)
+            entries += _public_entries(entry.path, walk)
+    return entries
+
+
+def _public_names(path: Path, walk: _Walk) -> list[str]:
+    """A module's `__all__`, or its public definitions and in-package imports."""
+    tree = walk.parse(path)
+    names = _dunder_all(tree)
+    if names is not None:
+        return names
+    names = []
+    for node in tree.body:
+        if isinstance(node, ast.ImportFrom):
+            if _import_target(path, node, walk.pkg_dir) is not None:
+                names += [a.asname or a.name for a in node.names if a.name != "*"]
+        else:
+            names += _defined_names(node)
+    return [n for n in names if not n.startswith("_")]
+
+
+def _dunder_all(tree: ast.Module) -> list[str] | None:
+    """Return the literal `__all__` list of a module, if it has one."""
+    for node in tree.body:
+        if "__all__" in _defined_names(node):
+            value = node.value  # ty: ignore[unresolved-attribute]
+            return [str(v) for v in ast.literal_eval(value)]
+    return None
+
+
+def _defined_names(node: ast.stmt) -> list[str]:
+    """Names a top-level statement defines (not imports)."""
+    if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+        return [node.name]
+    if isinstance(node, ast.TypeAlias) and isinstance(node.name, ast.Name):
+        return [node.name.id]
+    if isinstance(node, ast.Assign):
+        return [t.id for t in node.targets if isinstance(t, ast.Name)]
+    if (
+        isinstance(node, ast.AnnAssign)
+        and node.value is not None
+        and isinstance(node.target, ast.Name)
+    ):
+        return [node.target.id]
+    return []
+
+
+def _resolve(path: Path, name: str, walk: _Walk, depth: int = 0) -> Entry:
+    """Follow `name` from module `path` to the node that defines it."""
+    if depth > MAX_IMPORT_DEPTH:
+        return Entry(name, path, None)
+    body = walk.parse(path).body
+    for idx, node in enumerate(body):
+        if name in _defined_names(node):
+            return Entry(name, path, node, doc=_attribute_doc(body, idx))
+    for node in body:
+        if not isinstance(node, ast.ImportFrom):
+            continue
+        for alias in node.names:
+            if (alias.asname or alias.name) != name:
+                continue
+            target = _import_target(path, node, walk.pkg_dir)
+            if target is None:
+                return Entry(name, path, None, origin=node.module)
+            sub = _submodule(target, alias.name)
+            if sub is not None:
+                return Entry(name, sub, None, is_module=True)
+            entry = _resolve(target, alias.name, walk, depth + 1)
+            entry.name = name
+            return entry
+    return Entry(name, path, None)
+
+
+def _attribute_doc(body: list[ast.stmt], idx: int) -> str | None:
+    """The string literal directly after an assignment (attribute docstring)."""
+    if idx + 1 < len(body):
+        nxt = body[idx + 1]
+        if (
+            isinstance(nxt, ast.Expr)
+            and isinstance(nxt.value, ast.Constant)
+            and isinstance(nxt.value.value, str)
+        ):
+            return nxt.value.value
+    return None
+
+
+def _import_target(path: Path, node: ast.ImportFrom, pkg_dir: Path) -> Path | None:
+    """File a `from X import ...` points at, or None if outside the package."""
+    if node.level:
+        base = path.parent
+        for _ in range(node.level - 1):
+            base = base.parent
+        parts = node.module.split(".") if node.module else []
+    else:
+        mod = node.module or ""
+        if mod != pkg_dir.name and not mod.startswith(pkg_dir.name + "."):
+            return None
+        base = pkg_dir.parent
+        parts = mod.split(".")
+    target = base.joinpath(*parts)
+    if (target / "__init__.py").is_file():
+        return target / "__init__.py"
+    if target.with_suffix(".py").is_file():
+        return target.with_suffix(".py")
+    return None
+
+
+def _submodule(target: Path, name: str) -> Path | None:
+    """If `from pkg import name` names a submodule rather than an object."""
+    if target.name != "__init__.py":
+        return None
+    sub = target.parent / name
+    if (sub / "__init__.py").is_file():
+        return sub / "__init__.py"
+    if sub.with_suffix(".py").is_file():
+        return sub.with_suffix(".py")
+    return None
+
+
+def _module_name(path: Path, pkg_dir: Path) -> str:
+    """Dotted module name of a file inside the package."""
+    parts = list(path.relative_to(pkg_dir.parent).with_suffix("").parts)
+    if parts[-1] == "__init__":
+        parts.pop()
+    return ".".join(parts)
+
+
+def _render_entry(entry: Entry) -> list[str]:
+    """Markdown lines for one public name."""
+    node = entry.node
+    name = entry.name
+    if isinstance(node, ast.ClassDef):
+        return _render_class(name, node)
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        sig = f"{name}{_signature(node, drop_first=False)}"
+        lines = [f"### {name}", "", "```python", sig, "```"]
+        return lines + _summary_block(ast.get_docstring(node))
+    if isinstance(node, ast.TypeAlias):
+        alias = " ".join(ast.unparse(node).split())
+        lines = [f"### {name}", "", "```python", alias, "```"]
+        return lines + _summary_block(entry.doc)
+    if entry.origin is not None:
+        root_pkg = entry.origin.split(".")[0]
+        note = f"Re-exported from `{entry.origin}`"
+        if root_pkg.startswith("gri_"):
+            note += f"; see the `{root_pkg}` package's own docs/{SUMMARY_NAME}"
+        return [f"### {name}", "", note + "."]
+    return [f"### {name}", "", "(definition not found by the generator)"]
+
+
+def _render_class(name: str, node: ast.ClassDef) -> list[str]:
+    """Markdown lines for a class: constructor, members, operators."""
+    bases = ", ".join(ast.unparse(b) for b in node.bases)
+    lines = [f"### class {name}" + (f"({bases})" if bases else "")]
+    lines += _summary_block(_first_paragraph(ast.get_docstring(node)))
+
+    methods = _public_methods(node)
+    init = methods.pop("__init__", None)
+    new = methods.pop("__new__", None)
+    init = init or new
+    base_names = {ast.unparse(b).split(".")[-1] for b in node.bases}
+    fields = _class_fields(node)
+    if init is not None:
+        lines += ["", "```python", f"{name}{_signature(init)}", "```"]
+    elif base_names & ENUM_BASES:
+        lines += ["", "Members: " + ", ".join(f"`{f[0]}`" for f in fields)]
+        fields = []
+    if fields:
+        ctor = _has_decorator(node, "dataclass") or "NamedTuple" in base_names
+        label = "Fields (the constructor arguments, in order):" if ctor else "Fields:"
+        lines += ["", label, ""]
+        lines += [f"- `{f[0]}{f[1]}`" + _dash(f[2]) for f in fields]
+
+    props = [m for m in methods.values() if _has_decorator(m, "property")]
+    if props:
+        lines += ["", "Properties:", ""]
+        lines += [_property_line(p) for p in props]
+    plain = [m for m in methods.values() if m not in props]
+    if plain:
+        lines += ["", "Methods:", ""]
+        lines += [_method_line(m) for m in plain]
+    ops = _operators(node)
+    if ops:
+        lines += ["", "Operators: " + ", ".join(f"`{op}`" for op in ops)]
+    return lines
+
+
+def _public_methods(node: ast.ClassDef) -> dict[str, _Def]:
+    """Public methods of a class, last definition wins (skips overload stubs)."""
+    methods: dict[str, _Def] = {}
+    for item in node.body:
+        if not isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        name = item.name
+        public = not name.startswith("_") or name in LISTED_DUNDERS
+        if not (public or name in ("__init__", "__new__")):
+            continue
+        if _has_decorator(item, "overload") or _is_setter(item):
+            continue
+        methods[name] = item
+    return methods
+
+
+def _class_fields(node: ast.ClassDef) -> list[tuple[str, str, str | None]]:
+    """Class-level annotated or assigned names: (name, ': type = default', doc)."""
+    fields: list[tuple[str, str, str | None]] = []
+    body = node.body
+    for idx, item in enumerate(body):
+        if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
+            if item.target.id.startswith("_"):
+                continue
+            text = f": {ast.unparse(item.annotation)}"
+            if item.value is not None:
+                text += f" = {_short(ast.unparse(item.value))}"
+            fields.append((item.target.id, text, _attribute_doc(body, idx)))
+        elif isinstance(item, ast.Assign) and not _is_typing_factory(item.value):
+            text = f" = {_short(ast.unparse(item.value))}"
+            doc = _attribute_doc(body, idx)
+            fields += [
+                (t.id, text, doc)
+                for t in item.targets
+                if isinstance(t, ast.Name) and not t.id.startswith("_")
+            ]
+    return fields
+
+
+def _is_typing_factory(value: ast.expr) -> bool:
+    """True for `T = TypeVar(...)` and similar typing declarations."""
+    if not isinstance(value, ast.Call):
+        return False
+    return ast.unparse(value.func).split(".")[-1] in TYPING_FACTORIES
+
+
+def _signature(node: _Def, *, drop_first: bool = True) -> str:
+    """Render `(args) -> ret` in PEP 8 spacing, dropping self/cls if bound."""
+    args = node.args
+    positional = [*args.posonlyargs, *args.args]
+    pad = len(positional) - len(args.defaults)
+    defaults: list[ast.expr | None] = [None] * pad + list(args.defaults)
+    params = [_param(a, d) for a, d in zip(positional, defaults, strict=True)]
+    n_posonly = len(args.posonlyargs)
+    if drop_first and positional and not _has_decorator(node, "staticmethod"):
+        params.pop(0)
+        n_posonly = max(n_posonly - 1, 0)
+    if n_posonly:
+        params.insert(n_posonly, "/")
+    if args.vararg is not None:
+        params.append("*" + _param(args.vararg, None))
+    elif args.kwonlyargs:
+        params.append("*")
+    params += [
+        _param(a, d) for a, d in zip(args.kwonlyargs, args.kw_defaults, strict=True)
+    ]
+    if args.kwarg is not None:
+        params.append("**" + _param(args.kwarg, None))
+    ret = f" -> {ast.unparse(node.returns)}" if node.returns is not None else ""
+    return f"({', '.join(params)}){ret}"
+
+
+def _param(arg: ast.arg, default: ast.expr | None) -> str:
+    """One parameter: `x`, `x=1`, `x: int`, or `x: int = 1`."""
+    text = arg.arg
+    if arg.annotation is not None:
+        text += f": {ast.unparse(arg.annotation)}"
+        if default is not None:
+            text += f" = {ast.unparse(default)}"
+    elif default is not None:
+        text += f"={ast.unparse(default)}"
+    return text
+
+
+def _property_line(node: _Def) -> str:
+    """List item for a property: name, type, summary."""
+    ret = f": {ast.unparse(node.returns)}" if node.returns is not None else ""
+    return f"- `{node.name}{ret}`" + _dash(ast.get_docstring(node))
+
+
+def _method_line(node: _Def) -> str:
+    """List item for a method: signature, kind, summary."""
+    kind = ""
+    if _has_decorator(node, "staticmethod"):
+        kind = " (staticmethod)"
+    elif _has_decorator(node, "classmethod"):
+        kind = " (classmethod)"
+    sig = f"{node.name}{_signature(node)}"
+    return f"- `{sig}`{kind}" + _dash(ast.get_docstring(node))
+
+
+def _operators(node: ast.ClassDef) -> list[str]:
+    """Operators a class defines, in a fixed order."""
+    defined = {
+        item.name
+        for item in node.body
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef))
+    }
+    ops = [op for dunder, op in OPERATORS.items() if dunder in defined]
+    if _has_decorator(node, "total_ordering"):
+        ops += [op for op in ORDERING_OPS if op not in ops]
+        ops.sort(key=list(OPERATORS.values()).index)
+    return ops
+
+
+def _has_decorator(node: ast.stmt, name: str) -> bool:
+    """True if a def or class carries a decorator whose last name is `name`."""
+    for dec in getattr(node, "decorator_list", []):
+        target = dec.func if isinstance(dec, ast.Call) else dec
+        if ast.unparse(target).split(".")[-1] == name:
+            return True
+    return False
+
+
+def _is_setter(node: _Def) -> bool:
+    """True for `@x.setter` / `@x.deleter` property accessors."""
+    return any(
+        isinstance(dec, ast.Attribute) and dec.attr in ("setter", "deleter")
+        for dec in node.decorator_list
+    )
+
+
+def _is_constant(entry: Entry) -> bool:
+    """True for a module-level assignment (a constant or module variable)."""
+    return isinstance(entry.node, (ast.Assign, ast.AnnAssign))
+
+
+def _constant_line(entry: Entry) -> str:
+    """List item for a constant: `NAME: type = value` and its docstring."""
+    node = entry.node
+    if not isinstance(node, (ast.Assign, ast.AnnAssign)):
+        raise TypeError(f"{entry.name} is not a constant")
+    return f"- `{_constant(entry.name, node)}`" + _dash(entry.doc)
+
+
+def _constant(name: str, node: ast.Assign | ast.AnnAssign) -> str:
+    """Render a module constant as `NAME: type = value`."""
+    text = name
+    if isinstance(node, ast.AnnAssign):
+        text += f": {ast.unparse(node.annotation)}"
+    if node.value is not None:
+        text += f" = {_short(ast.unparse(node.value))}"
+    return text
+
+
+def _short(value: str) -> str:
+    """Elide a long rendered value."""
+    value = " ".join(value.split())
+    return value if len(value) <= MAX_VALUE_LEN else "..."
+
+
+def _first_paragraph(doc: str | None) -> str | None:
+    """The first paragraph of a docstring, joined onto one line."""
+    if not doc:
+        return None
+    return " ".join(doc.strip().split("\n\n")[0].split())
+
+
+def _summary(doc: str | None) -> str | None:
+    """The summary (first) line of a docstring."""
+    if not doc:
+        return None
+    return doc.strip().splitlines()[0].strip()
+
+
+def _summary_block(doc: str | None) -> list[str]:
+    """A blank line and the docstring summary, or nothing."""
+    summary = _summary(doc)
+    return ["", summary] if summary else []
+
+
+def _dash(doc: str | None) -> str:
+    """Suffix ' -- summary' for list items, or empty."""
+    summary = _summary(doc)
+    return f" -- {summary}" if summary else ""
+
+
+if __name__ == "__main__":
+    main()

{gri_plot-0.2.6 → gri_plot-0.2.7}/.gitignore

@@ -16,6 +16,7 @@ lib64/
 .version
 .pytest_cache/
 .mypy_cache/
+.ipynb_checkpoints/
 testreports/
 .VSCodeCounter/
 .coverage
@@ -27,6 +28,13 @@ coverage.xml
 CLAUDE.md
 AGENTS.md
 
+### Internal working notes -- plans and todos stay out of the public repos ###
+TODO.md
+PLAN*.md
+
+### Local scratch dir -- conventional throwaway working area (contents ignored) ###
+_scratch/*
+
 ### Credentials ###
 .env*
 *.key
@@ -34,3 +42,4 @@ AGENTS.md
 *.p12
 .cdsapirc
 .ecmwfdatastoresrc
+public/

{gri_plot-0.2.6 → gri_plot-0.2.7}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 GeoSol Research Inc.
+Copyright (c) 2025-2026 GeoSol Research Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{gri_plot-0.2.6 → gri_plot-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: gri-plot
-Version: 0.2.6
+Version: 0.2.7
 Summary: 3D geolocation visualization and 2D plotting utilities built on Plotly
 Project-URL: Homepage, https://geosolresearch.com
 Project-URL: Repository, https://gitlab.com/geosol-foss/python/gri-plot
@@ -33,6 +33,19 @@ Description-Content-Type: text/markdown
 
 This library renders parametric geometric shapes (ellipsoids, spheres, cones, cylinders) and observable surfaces that inherit from them (AOA cones, line-of-sight rays, range spheres) as interactive 3D meshes. It also provides shorthand functions for 2D scatter plots and geographic maps.
 
+## Documentation
+
+The wheel ships its documentation inside the package, in `gri_plot/docs/`,
+so it is available wherever the package is installed:
+
+- `overview.md` -- conventions, error ellipses, 3D shapes and measurement
+  surfaces, 3D figures, and maps
+- `api_summary.md` -- every public class and signature (generated)
+
+Print the directory with
+`python -c "import gri_plot, pathlib; print(pathlib.Path(gri_plot.__file__).parent / 'docs')"`.
+Every example in those files is run by the test suite.
+
 ## Installation
 
 ```bash

{gri_plot-0.2.6 → gri_plot-0.2.7}/README.md

@@ -8,6 +8,19 @@
 
 This library renders parametric geometric shapes (ellipsoids, spheres, cones, cylinders) and observable surfaces that inherit from them (AOA cones, line-of-sight rays, range spheres) as interactive 3D meshes. It also provides shorthand functions for 2D scatter plots and geographic maps.
 
+## Documentation
+
+The wheel ships its documentation inside the package, in `gri_plot/docs/`,
+so it is available wherever the package is installed:
+
+- `overview.md` -- conventions, error ellipses, 3D shapes and measurement
+  surfaces, 3D figures, and maps
+- `api_summary.md` -- every public class and signature (generated)
+
+Print the directory with
+`python -c "import gri_plot, pathlib; print(pathlib.Path(gri_plot.__file__).parent / 'docs')"`.
+Every example in those files is run by the test suite.
+
 ## Installation
 
 ```bash