diff --git a/scripts/autolink.py b/scripts/autolink.py index 4f5a4f7..955d775 100644 --- a/scripts/autolink.py +++ b/scripts/autolink.py @@ -13,7 +13,7 @@ badge; elsewhere a cobrapy name has to be dotted (``Model.optimize``) or snake_case (``read_sbml_model``), so ordinary words are never linked. -Every span in a table row is linked, so the "Functions on this page" table +Every span in a table row is linked, so the "Functions" table links each entry; in prose only the first mention of a name per section is. The cobrapy badge in a table row points at the first cobrapy object linked in that row instead of cobrapy's index page. diff --git a/scripts/check_site.py b/scripts/check_site.py index e2394dc..cde0d21 100644 --- a/scripts/check_site.py +++ b/scripts/check_site.py @@ -39,7 +39,7 @@ # Scripts that every site copies unchanged from the plugin. SHARED_SCRIPTS = [ "project.py", "api_index.py", "gen_api_pages.py", "autolink.py", - "check_names.py", "run_examples.py", "check_site.py", "report_broken_links.py", + "check_names.py", "check_style.py", "run_examples.py", "check_site.py", "report_broken_links.py", ] WRONG_NAMES = { @@ -64,7 +64,7 @@ # Names of configuration files and folders are not mentions of a tool. CONFIG_NAMES = re.compile(r"claude\.md|\.claude(?:-plugin)?\b", re.I) -GUIDE_EXPECTED = ["Functions on this page", "What can go wrong", "See also"] +GUIDE_EXPECTED = ["Functions", "Troubleshooting", "See also"] # A page that explains a concept instead of a task opts out of the anatomy. CONCEPT_MARKER = "" @@ -327,7 +327,7 @@ def check_pages(site: Path, files: list[Path]) -> list[Finding]: out.append(Finding("P", "error", rel, f"heading level jumps from H{skip[1]} to H{skip[2]} (strict build warns)", skip[0])) if rel.startswith("docs/guide/") and p.name != "index.md" and CONCEPT_MARKER not in text: for h in GUIDE_EXPECTED: - if not re.search(rf"^#+ {re.escape(h)}", text, re.M): + if not re.search(rf"^(?:#+ |:{{3,}}\{{\w+\}} ){re.escape(h)}", text, re.M): out.append(Finding("P", "warning", rel, f"no '{h}' section")) return out diff --git a/scripts/check_style.py b/scripts/check_style.py new file mode 100644 index 0000000..d43e8f1 --- /dev/null +++ b/scripts/check_style.py @@ -0,0 +1,305 @@ +#!/usr/bin/env python3 +"""Report the prose patterns that craft/skills/writing/references/docs-prose.md discourages. + +Usage: check_style.py [PATH ...] [--summary] [--strict] + +A PATH that is a site directory (it has a docs/ folder) is scanned page by page with all +pattern families; the Markdown pages under docs/ are scanned, not docs/api/ and not +generated pages. A PATH that is a Markdown file is scanned with the general families only, +which hold for every text (README, pull request drafts, comments). A Python or MATLAB file is scanned in its docstrings or its leading help block with the same families. Code blocks, inline code, +link targets and directive lines are ignored. Prints one line per +page and pattern family as ``S warning path:line N x family: first match``. A pattern is +a heuristic: one hit can be correct, a family that recurs on a page is a reason to rewrite +the page. ``--summary`` prints the rate per 1000 words of every family over the site and +the pages with the highest rates. The exit code is 0 unless ``--strict`` is given and there +is a finding. +""" + +from __future__ import annotations + +import re +import sys +from collections import Counter, defaultdict +from pathlib import Path + +EM_DASH = chr(0x2014) +EN_DASH = chr(0x2013) + +INTENSIFIERS = ( + "actually|genuine(?:ly)?|really|exactly|simply|just|entirely|completely|essentially|" + "effectively|basically|clearly|obviously|quite|very|truly|merely|fundamentally" +) +EVALUATIVE = ( + "easy|easily|simple|obvious|important|key|crucial|critical|useful|robust|powerful|" + "comprehensive|straightforward|seamless(?:ly)?|elegant|convenient|painful|sensible" +) +FIGURATIVE = ( + r"travels?|lands?|buys?|hooks?|traps?|silently|quietly|loses|" + r"sits? (?:in|on|at|inside|where)|lives? (?:in|on|at|inside)|" + r"fold(?:s|ed|ing)? into|housekeeping|(?:on|from) the \w+ side|routes?" +) +INFLATED = r"utili[sz]\w*|leverag\w+|facilitat\w+|foster\w*|showcas\w+|underscor\w+" + +# Family name -> (pattern, flags). Each match counts once. +FAMILIES: dict[str, re.Pattern[str]] = { + "second person": re.compile(r"\b(?:you|your|yours|yourself)\b", re.I), + "first person plural": re.compile(r"\b(?:we|our|ours|us)\b(?! recommend)", re.I), + "contraction": re.compile(r"\b\w+(?:n't|'re|'ve|'ll|'d)\b|\b(?:it|that|there|what|here|let)'s\b", re.I), + "intensifier": re.compile(rf"\b(?:{INTENSIFIERS})\b", re.I), + "evaluative word": re.compile(rf"\b(?:{EVALUATIVE})\b", re.I), + "figurative verb": re.compile(rf"\b(?:{FIGURATIVE})\b", re.I), + "inflated verb": re.compile(rf"\b(?:{INFLATED})\b", re.I), + "contrast scaffolding": re.compile( + r"\bnot (?:just|only|merely|simply)\b|\bnot an? [^.;:,]{1,60}\bbut\b|\bnot [^.;:,]{1,40}, but\b" + r"|\brather than\b|\binstead of\b", + re.I, + ), + "and not": re.compile( + r"\b(?:and|but) not (?:a|an|the|by|in|to|for|as|on|of|with|its|their|from|at)\b" + r"|, not (?:a|an|the|by|in|to|for|as|on|of|with|its|their|from|at)\b", + re.I, + ), + "restriction word": re.compile(r"\bonly\b", re.I), + "passive instruction": re.compile( + r"\b(?:is|are) (?:set|checked|inspected|closed|opened|added|run|restricted|excluded|compared) " + r"(?:first|before|afterwards)\b", + re.I, + ), + "evaluative tail": re.compile( + r", (?:which is why|which means|making|ensuring|allowing|thereby|so that)\b" + r"|\bThis is (?:what|why)\b|\bThat is why\b", + ), + "labelled opener": re.compile( + r"\b(?:the )?(?:practical consequence|catch|upshot|takeaway|bottom line|short version|key point|trick)\s*:", + re.I, + ), + "reference to the document": re.compile( + r"\bthis (?:page|section|chapter)\b|\bin this (?:guide|tutorial)\b" + r"|\b(?:as )?(?:shown|mentioned|noted|described|discussed|listed|given) (?:above|below|earlier)\b" + r"|\b(?:table|example|code|list|figure) (?:above|below)\b", + re.I, + ), + "directive to the reader": re.compile( + r"\b(?:make sure|be careful|be aware|keep in mind|bear in mind|do not forget|remember (?:that|to))\b", re.I + ), + "copula avoidance": re.compile(r"\b(?:serves? as|acts? as|functions? as|boasts?)\b", re.I), + "generic attribution": re.compile( + r"\b(?:generally|commonly|typically|in practice|arguably|potentially|perhaps|presumably|it appears that)\b", re.I + ), + "american spelling": re.compile( + r"\b(?:behavior\w*|colors?|normaliz\w+|artifacts?|analyz\w+|optimiz\w+|initializ\w+|" + r"visualiz\w+|standardiz\w+|organiz\w+|modeling|modeled|centers?|catalyz\w+)\b", + re.I, + ), + "italic emphasis": re.compile(r"(? list[tuple[int, str]]: + """Lines of prose with code, inline code, link targets and directive syntax removed.""" + out = [] + in_code = False + for i, raw in enumerate(text.splitlines(), 1): + stripped = raw.lstrip() + if stripped.startswith(("```", "~~~")): + in_code = not in_code + continue + if in_code or not stripped: + continue + if re.match(r":{3,}(?:\{|\s*$)", stripped) and not re.match(r":{3,}\{(?:note|warning|tip|important|admonition)\}", stripped): + continue + if re.match(r":\w[\w-]*:", stripped) or stripped.startswith(("`` + anywhere in the page -- the page is not executed at all (use for pages whose + examples need BLAST, a KEGG download, or a commercial solver). +```` + immediately before a ```python block -- that one block is neither executed + nor checked, but the ones after it still run. +```` + the block selects Gurobi (a MILP the page runs on Gurobi rather than on the + bundled GLPK): it runs where Gurobi is available (``--gurobi`` or + ``DOCS_GUROBI=1``, which CI sets when a licence is configured) and is + skipped everywhere else. + +```` + anywhere in the page -- the cross-tab check below is not applied to it, + because the two tabs genuinely print different things. + +An expected-output block consisting of a single ``...`` matches anything, and +``...`` inside a block matches any run of characters -- the same convention as +doctest's ELLIPSIS. Use it for timings, paths and long tables. + +When both languages run, the tabs of each section are compared: a value printed +under the same label with the opposite sign in the other tab is reported. That is +the one thing the per-block check cannot see, since a block that runs cleanly and +prints a wrong number still matches the wrong number written beneath it. +""" + +from __future__ import annotations + +import argparse +import ast +import contextlib +import difflib +import io +import os +import json +import re +import shutil +import subprocess +import sys +import tempfile +import traceback +from dataclasses import dataclass, field +from pathlib import Path + +HERE = Path(__file__).resolve().parent +ROOT = HERE.parent +DEFAULT_TARGET = ROOT / "docs" / "guide" +DATA_DIR = ROOT / "docs" / "data" + +# Settings of the site: the paths of the toolboxes and the ``examples`` section +# of project.yml. +sys.path.insert(0, str(HERE)) +from project import load as _load_project # noqa: E402 + +_PROJECT = _load_project() + +# The solver the pasted numbers are produced with. GLPK ships with cobrapy as a +# wheel, so it is the one solver every reader and every CI runner is guaranteed +# to have; pinning it keeps the output blocks reproducible. +DEFAULT_SOLVER = _PROJECT.examples.get("solver", "glpk") + +# The MATLAB toolbox for the MATLAB half: the submodule checkout, and whatever +# MATLAB the machine has. +MATLAB_DIR = _PROJECT.matlab_src +MATLAB_SOLVER = DEFAULT_SOLVER +LANGUAGES = ("python", "matlab") + +# The info string of an expected-output fence: a bare ```text directly below the +# code block. A titled text fence (```text title="tasks.txt") is an input shown +# to the reader, not output. +OUTPUT_INFO = "text" + +SKIP_FILE = "run-examples: skip-file" +SKIP_BLOCK = "run-examples: skip" +NEEDS_GUROBI = "run-examples: needs-gurobi" + +# Examples that select Gurobi run only where Gurobi is available: on a machine +# with a licence, and in CI when the workflow has one configured. They are +# skipped everywhere else rather than failing, so a reader without Gurobi still +# gets a green run. +GUROBI_ENABLED = os.environ.get("DOCS_GUROBI", "") not in ("", "0") + +_FENCE_OPEN = re.compile(r"^(?P[ \t]*)(?P`{3,})(?P.*)$") +_HTML_COMMENT = re.compile(r"") + + +# -------------------------------------------------------------------------- +# Markdown scanning +# -------------------------------------------------------------------------- + + +@dataclass +class Fence: + """One fenced code block, wherever it sits in the page.""" + + indent: str + info: str + body: list[str] + start: int # index of the opening ``` line + end: int # index of the closing ``` line + + @property + def language(self) -> str: + return self.info.strip().split(maxsplit=1)[0] if self.info.strip() else "" + + @property + def code(self) -> str: + strip = len(self.indent) + return "\n".join(line[strip:] if line[:strip].isspace() or not line[:strip] else line.lstrip() for line in self.body) + + +@dataclass +class Example: + """A ```python block, with the output block that follows it, if any.""" + + page: Path + number: int + code_fence: Fence + section: str = "" + section_index: int = 0 + output_fence: Fence | None = None + skip: bool = False + actual: str | None = None + error: str | None = None + status: str = "pending" # pending | ok | mismatch | error | skipped + + +@dataclass +class PageResult: + page: Path + language: str = "python" + examples: list[Example] = field(default_factory=list) + skipped_page: bool = False + # The page as it was when the examples were collected. --update rewrites + # blocks by line number, so a page edited while a run is in flight would be + # rewritten from stale positions and end up with duplicated fences. + source: str = "" + + @property + def failures(self) -> list[Example]: + return [e for e in self.examples if e.status in {"mismatch", "error"}] + + +def scan_fences(lines: list[str]) -> list[Fence]: + """Return every fenced block in ``lines``, including indented ones. + + Content tabs indent their code by four spaces, so a naive ``^```` scan finds + nothing on a dual-language page. Closing fences are matched on the same + indentation and at least as many backticks as the opening fence, which is + what CommonMark requires and what pymdownx accepts. + """ + fences: list[Fence] = [] + i = 0 + while i < len(lines): + match = _FENCE_OPEN.match(lines[i]) + if not match or "`" in match.group("info"): + i += 1 + continue + indent, ticks, info = match.group("indent"), match.group("ticks"), match.group("info") + close = re.compile(rf"^{re.escape(indent)}`{{{len(ticks)},}}[ \t]*$") + j = i + 1 + while j < len(lines) and not close.match(lines[j]): + j += 1 + if j >= len(lines): # unterminated fence -- leave it to the markdown build + break + fences.append(Fence(indent=indent, info=info, body=lines[i + 1 : j], start=i, end=j)) + i = j + 1 + return fences + + +def _marker_above(lines: list[str], fence: Fence) -> str | None: + """The ```` marker just above the block, if any.""" + k = fence.start - 1 + while k >= 0 and not lines[k].strip(): + k -= 1 + if k < 0: + return None + for comment in _HTML_COMMENT.finditer(lines[k]): + body = comment.group("body").strip() + if body in (SKIP_BLOCK, NEEDS_GUROBI): + return body + return None + + +def _block_is_skipped(lines: list[str], fence: Fence) -> bool: + marker = _marker_above(lines, fence) + if marker == SKIP_BLOCK: + return True + if marker == NEEDS_GUROBI: + return not GUROBI_ENABLED + return False + + +def collect_examples(page: Path, language: str = "python") -> PageResult: + source = page.read_text(encoding="utf-8") + lines = source.splitlines() + result = PageResult(page=page, language=language, source=source) + if any(SKIP_FILE in line for line in lines): + result.skipped_page = True + return result + + headings = [ + (i, line.lstrip("#").strip()) + for i, line in enumerate(lines) + if line.startswith("#") + ] + + def section_of(line_no: int) -> str: + title = "" + for start, text in headings: + if start < line_no: + title = text + else: + break + return title + + seen_per_section: dict[str, int] = {} + fences = scan_fences(lines) + for index, fence in enumerate(fences): + if fence.language != language: + continue + section = section_of(fence.start) + seen_per_section[section] = seen_per_section.get(section, 0) + 1 + output = None + if index + 1 < len(fences): + nxt = fences[index + 1] + gap = lines[fence.end + 1 : nxt.start] + if all(not line.strip() for line in gap) and nxt.info.strip() == OUTPUT_INFO: + output = nxt + result.examples.append( + Example( + page=page, + number=len(result.examples) + 1, + code_fence=fence, + output_fence=output, + skip=_block_is_skipped(lines, fence), + section=section, + section_index=seen_per_section[section], + ) + ) + return result + + +# -------------------------------------------------------------------------- +# Execution +# -------------------------------------------------------------------------- + + +def _exec_block(code: str, namespace: dict) -> str: + """Run one block and return what a notebook cell would have shown. + + Everything printed is captured, and if the block ends in a bare expression + its repr is appended -- so ``model.reactions.get_by_id("r_0001")`` on the + last line produces output without the page having to wrap it in ``print``. + """ + tree = ast.parse(code) + buffer = io.StringIO() + last_expr: ast.Expr | None = None + body = tree.body + if body and isinstance(body[-1], ast.Expr): + last_expr = body[-1] # type: ignore[assignment] + body = body[:-1] + + with contextlib.redirect_stdout(buffer): + if body: + exec(compile(ast.Module(body=body, type_ignores=[]), "", "exec"), namespace) + if last_expr is not None: + value = eval( # noqa: S307 -- documentation snippets, run deliberately + compile(ast.Expression(last_expr.value), "", "eval"), namespace + ) + if value is not None: + print(repr(value), file=buffer) + return buffer.getvalue() + + +def run_page(result: PageResult, solver: str | None) -> None: + """Execute a page's blocks in one namespace inside a scratch directory.""" + namespace: dict = {"__name__": "__main__"} + workdir = Path(tempfile.mkdtemp(prefix="docs-examples-")) + if DATA_DIR.is_dir(): + for item in DATA_DIR.iterdir(): + if item.is_file() and item.name != "README.md": + shutil.copy2(item, workdir / item.name) + previous_cwd = Path.cwd() + try: + os.chdir(workdir) + if solver: + _pin_solver(solver) + for example in result.examples: + if example.skip: + example.status = "skipped" + continue + try: + example.actual = tidy_python( + _exec_block(example.code_fence.code, namespace) + ) + example.status = "ok" # provisional; compared below + except BaseException: # noqa: BLE001 -- a failing snippet is a finding + example.error = traceback.format_exc(limit=3) + example.status = "error" + break # later blocks depend on this one, so stop the page here + finally: + os.chdir(previous_cwd) + shutil.rmtree(workdir, ignore_errors=True) + + +def find_matlab() -> str | None: + """The MATLAB executable, from DOCS_MATLAB or the PATH.""" + explicit = os.environ.get("DOCS_MATLAB") + if explicit: + return explicit if Path(explicit).exists() else None + return shutil.which("matlab") + + +_MATLAB_DRIVER = """function docs_run(docsrun_harness) +% Run every block of every page and write the captured output as JSON. +% One workspace per page, so a page's blocks build on each other exactly as the +% reader's session would. +% Warnings are part of what a reader sees, but their HTML links and stack +% traces name temporary paths that change every run -- turn both off so the +% captured text is stable. +feature('hotlinks', 'off'); +warning('off', 'backtrace'); +if ~isempty(getenv('GUROBI_HOME')) + addpath(fullfile(getenv('GUROBI_HOME'), 'matlab')); +end +@PREFS_SAVE@docsrun_pages = dir(fullfile(docsrun_harness, 'page_*')); +docsrun_out = struct('page', {}, 'block', {}, 'output', {}, 'error', {}); +addpath(genpath('@MATLAB_SRC@')); +@START@for docsrun_p = 1:numel(docsrun_pages) + docsrun_dir = fullfile(docsrun_harness, docsrun_pages(docsrun_p).name); + docsrun_blocks = dir(fullfile(docsrun_dir, 'block_*.m')); + cd(docsrun_dir); + clearvars -except docsrun_* +@PAGE_START@ for docsrun_b = 1:numel(docsrun_blocks) + [~, docsrun_name] = fileparts(docsrun_blocks(docsrun_b).name); + docsrun_entry = struct( ... + 'page', docsrun_pages(docsrun_p).name, ... + 'block', docsrun_name, 'output', '', 'error', ''); + try + docsrun_entry.output = evalc(docsrun_name); + catch docsrun_err + docsrun_entry.error = docsrun_err.message; + end + docsrun_out(end + 1) = docsrun_entry; %#ok + if ~isempty(docsrun_entry.error) + break % later blocks depend on this one + end + end +end +@PREFS_RESTORE@docsrun_fid = fopen(fullfile(docsrun_harness, 'results.json'), 'w'); +fwrite(docsrun_fid, jsonencode(docsrun_out)); +fclose(docsrun_fid); +end +""" + + +_PREFS_SAVE = """% The toolbox keeps its settings as MATLAB preferences, which +% outlive this process -- so remember whatever the machine had and put it back +% at the end. Without this, running the harness locally silently rewrites the +% reader's own settings. +docsrun_keys = {@KEYS@}; +docsrun_prefs = struct('name', {}, 'value', {}, 'had', {}); +for docsrun_k = 1:numel(docsrun_keys) + docsrun_key = docsrun_keys{docsrun_k}; + docsrun_had = ispref('@GROUP@', docsrun_key); + docsrun_val = []; + if docsrun_had + docsrun_val = getpref('@GROUP@', docsrun_key); + end + docsrun_prefs(end + 1) = struct( ... + 'name', docsrun_key, 'value', {docsrun_val}, 'had', docsrun_had); %#ok +end +""" + +_PREFS_RESTORE = """for docsrun_k = 1:numel(docsrun_prefs) + if docsrun_prefs(docsrun_k).had + setpref('@GROUP@', docsrun_prefs(docsrun_k).name, ... + docsrun_prefs(docsrun_k).value); + elseif ispref('@GROUP@', docsrun_prefs(docsrun_k).name) + rmpref('@GROUP@', docsrun_prefs(docsrun_k).name); + end +end +""" + + +def render_matlab_driver() -> str: + """The driver with the site's snippets from the ``examples`` section of project.yml.""" + ex = _PROJECT.examples + prefs = ex.get("matlab_preferences") or {} + save = restore = "" + if prefs: + keys = ", ".join(f"'{k}'" for k in prefs["keys"]) + save = _PREFS_SAVE.replace("@GROUP@", prefs["group"]).replace("@KEYS@", keys) + restore = _PREFS_RESTORE.replace("@GROUP@", prefs["group"]) + return ( + _MATLAB_DRIVER.replace("@PREFS_SAVE@", save) + .replace("@PREFS_RESTORE@", restore) + .replace("@START@", ex.get("matlab_start", "")) + .replace("@PAGE_START@", ex.get("matlab_page_start", "")) + .replace("@MATLAB_SRC@", MATLAB_DIR.as_posix()) + .replace("@SOLVER@", MATLAB_SOLVER) + ) + + +def prepare_matlab(results: list[PageResult], harness: Path) -> dict[str, PageResult]: + """Write the MATLAB harness: one directory per page, plus the driver. + + Split out from running it, because on GitHub-hosted runners MATLAB is only + licensed when it is started by ``matlab-actions/run-command`` -- so CI + prepares the harness, lets that action run the driver, and collects the + results afterwards. Locally, :func:`run_matlab` does all three in one go. + """ + harness.mkdir(parents=True, exist_ok=True) + page_dirs: dict[str, PageResult] = {} + runnable = [r for r in results if not r.skipped_page and r.examples] + for index, result in enumerate(runnable, start=1): + page_dir = harness / f"page_{index:02d}" + page_dir.mkdir(exist_ok=True) + page_dirs[page_dir.name] = result + if DATA_DIR.is_dir(): + for item in DATA_DIR.iterdir(): + if item.is_file() and item.name != "README.md": + shutil.copy2(item, page_dir / item.name) + for example in result.examples: + if example.skip: + example.status = "skipped" + continue + (page_dir / f"block_{example.number:02d}.m").write_text( + example.code_fence.code + chr(10), encoding="utf-8" + ) + + (harness / "docs_run.m").write_text(render_matlab_driver(), encoding="utf-8") + return page_dirs + + +# MATLAB wraps warning text to the width of the command window, which differs +# between a developer's machine and a CI runner, and pads it with backspace +# characters once hotlinks are off. Flatten each warning to one line so the same +# warning compares equal everywhere. +# A warning ends at a "]" that closes the line -- not at the first "]" in the +# text, which may well be part of a quoted task or reaction id. +_MATLAB_WARNING = re.compile( + r"\[Warning:.*?\](?=[ \t]*(?:\r?\n|$))", re.S +) + + +# Parallel Computing Toolbox chatter. Functions such as getAllowedBounds run in +# parallel, so the first one to be called opens a pool and says so -- naming a +# worker count that is a property of the machine, and only when no pool happens +# to be open already. Neither belongs in a documentation page. +_MATLAB_PARPOOL = re.compile( + r"^(Starting parallel pool \(parpool\).*|Connected to parallel pool.*|" + r"Parallel pool using the .* is shutting down\.)$" +) + + +# The toolboxes fetch third-party binaries (BLAST+, DIAMOND, hmmer) the first +# time a function needs one, and say so. Whether the line +# appears -- and its exact wording, which has drifted between toolbox versions +# ("Downloading blast+ from ...", "Downloading blast-2.17.0-...zip... +# COMPLETE") -- depends on what the machine has cached and which binary-fetch +# code is current, not on the example. Match on the leading word alone. +_BINARY_DOWNLOAD = re.compile(r"^Downloading .*$") + + +def tidy_matlab(text: str) -> str: + text = text.replace(chr(8), "") # backspaces left behind by hotlink removal + text = _MATLAB_WARNING.sub(lambda m: " ".join(m.group(0).split()), text) + keep = [ + line + for line in text.split(chr(10)) + if not _MATLAB_PARPOOL.match(line.strip()) + and not _BINARY_DOWNLOAD.match(line.strip()) + ] + return chr(10).join(keep) + + +# Solver chatter that is not the example's output: Gurobi's start-up banner -- +# which names the machine's licence -- and the LP files optlang writes to a +# temporary path that changes every run. Neither belongs in a documentation page, +# and the licence line must never be written into one. +_SOLVER_NOISE = re.compile( + r"^(Set parameter .*|Academic license.*|Restricted license.*|" + r"Read LP format model from file .*|Reading time = .*|" + r": \d+ rows, \d+ columns, \d+ nonzeros)$" +) + + +def tidy_python(text: str) -> str: + keep = [ + line + for line in text.split(chr(10)) + if not _SOLVER_NOISE.match(line.strip()) + and not _BINARY_DOWNLOAD.match(line.strip()) + ] + return chr(10).join(keep) + + +def collect_matlab( + page_dirs: dict[str, PageResult], harness: Path, diagnostics: str = "" +) -> None: + """Read what MATLAB captured and attach it to the examples.""" + results_file = harness / "results.json" + if not results_file.exists(): + for result in page_dirs.values(): + for example in result.examples: + if example.status != "skipped": + example.status = "error" + example.error = ( + "MATLAB produced no results. " + diagnostics.strip() + ) + return + + raw = json.loads(results_file.read_text(encoding="utf-8") or "[]") + if isinstance(raw, dict): # jsonencode collapses a one-element struct array + raw = [raw] + captured = {(entry["page"], entry["block"]): entry for entry in raw} + for page_name, result in page_dirs.items(): + for example in result.examples: + if example.status == "skipped": + continue + entry = captured.get((page_name, f"block_{example.number:02d}")) + if entry is None: + example.status = "error" + example.error = "not reached (an earlier block on this page failed)" + elif entry.get("error"): + example.status = "error" + example.error = entry["error"] + else: + example.actual = tidy_matlab(entry.get("output", "")) + example.status = "ok" + + +def run_matlab(results: list[PageResult], matlab: str) -> None: + """Prepare, run and collect in one go, with a locally licensed MATLAB. + + MATLAB takes tens of seconds to start, so all the pages share one process; + each still gets its own directory and a cleared workspace. + """ + if not [r for r in results if not r.skipped_page and r.examples]: + return + harness = Path(tempfile.mkdtemp(prefix="docs-matlab-")) + try: + page_dirs = prepare_matlab(results, harness) + command = [ + matlab, "-batch", + f"addpath('{harness.as_posix()}'); docs_run('{harness.as_posix()}')", + ] + completed = subprocess.run( # noqa: S603 -- our own generated script + command, cwd=str(ROOT), capture_output=True, text=True + ) + collect_matlab( + page_dirs, harness, completed.stderr or completed.stdout or "" + ) + finally: + shutil.rmtree(harness, ignore_errors=True) + + +def _pin_solver(solver: str) -> None: + try: + import cobra # noqa: PLC0415 -- optional, and only needed at run time + except ImportError: + return + try: + cobra.Configuration().solver = solver + except Exception as exc: # noqa: BLE001 -- report, do not abort the run + print(f"warning: could not select solver {solver!r}: {exc}", file=sys.stderr) + + +# -------------------------------------------------------------------------- +# Comparison +# -------------------------------------------------------------------------- + + +def normalise(text: str) -> str: + lines = [line.rstrip() for line in text.replace("\r\n", "\n").split("\n")] + while lines and not lines[0]: + lines.pop(0) + while lines and not lines[-1]: + lines.pop() + return "\n".join(lines) + + +def matches(expected: str, actual: str) -> bool: + """Compare with doctest-style ``...`` wildcards.""" + expected, actual = normalise(expected), normalise(actual) + if expected.strip() == "...": + return True + if "..." not in expected: + return expected == actual + pattern = ".*?".join(re.escape(part) for part in expected.split("...")) + return re.fullmatch(pattern, actual, flags=re.S) is not None + + +def compare(result: PageResult) -> None: + for example in result.examples: + if example.status != "ok" or example.output_fence is None: + continue + expected = "\n".join( + line[len(example.output_fence.indent) :] if line.startswith(example.output_fence.indent) else line + for line in example.output_fence.body + ) + if not matches(expected, example.actual or ""): + example.status = "mismatch" + + +# -------------------------------------------------------------------------- +# Cross-tab check +# -------------------------------------------------------------------------- + +# A labelled value: "growth: 0.0809 /h" -> ("growth", 0.0809). Comparing +# labels rather than loose numbers is what makes this precise: the two tabs of a +# step print the same labels by convention, while the rest of their output -- +# counts, dicts, warnings -- is free to differ. +_LABELLED = re.compile( + r"^(?P