From d945680cd81d9079431209252388ce0b01e43929 Mon Sep 17 00:00:00 2001 From: Chao Wang <26245345+ChaoWao@users.noreply.github.com> Date: Mon, 27 Jul 2026 23:44:42 -0700 Subject: [PATCH] Fix: make the docs build strict without suppressions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two gaps left the docs build weaker than it looked. A page absent from nav still built cleanly under --strict, showing up as one INFO line. So the rule docs/README.md states — a new doc needs a nav entry — was unenforceable, and a missing entry silently dropped the page out of the site's navigation. validation.nav.omitted_files now warns, which --strict treats as a failure. Verified both ways: a page left out of nav fails the build, and removing it passes again. Twenty-six existing pages are out of nav on purpose: the investigations log, the remote-L3 design set, and the per-code error pages are reached through their own index pages, and listing every entry would bury the rest of the tree. They are declared in not_in_nav so the check stays strict for everything else rather than being switched off. The nine parameters that griffe reported as documented-but-unannotated are annotated, so docs/_hooks/griffe_filter.py — which existed only to keep that one message from failing --strict — is deleted. The build now passes --strict with zero warnings and nothing suppressed. Two of those annotations needed a decision rather than a transcription. ChipWorker.init's `bins` is structurally typed: the docstring accepts any object exposing the *_path attributes, and the body reads dispatcher_path through getattr, so it is Any. Naming RuntimeBinaries would be both narrower than the contract and a dependency from simpler onto simpler_setup. ChipWorker.run's `handle` is a CallableHandle, imported under TYPE_CHECKING because the runtime import is deliberately lazy at its use site; PEP 563 is already on in both files, so the annotations cost no import. Co-Authored-By: Claude Opus 5 (1M context) --- docs/_hooks/griffe_filter.py | 45 -------------------------------- mkdocs.yml | 18 ++++++++++++- python/simpler/task_interface.py | 29 +++++++++++++++++--- python/simpler/worker.py | 2 +- 4 files changed, 44 insertions(+), 50 deletions(-) delete mode 100644 docs/_hooks/griffe_filter.py diff --git a/docs/_hooks/griffe_filter.py b/docs/_hooks/griffe_filter.py deleted file mode 100644 index c487264c1..000000000 --- a/docs/_hooks/griffe_filter.py +++ /dev/null @@ -1,45 +0,0 @@ -# Copyright (c) PyPTO Contributors. -# This program is free software, you can redistribute it and/or modify it under the terms and conditions of -# CANN Open Software License Agreement Version 2.0 (the "License"). -# Please refer to the License for details. You may not use this file except in compliance with the License. -# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, -# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. -# See LICENSE in the root of the software repository for the full text of the License. -# ----------------------------------------------------------------------------------------------------------- -"""Stop griffe's missing-annotation notices from failing ``--strict``. - -``--strict`` is what makes the build fail on a dead link, a page missing from -``nav``, or an anchor that does not exist — the checks worth gating on. It counts -warnings through ``mkdocs.utils.CountHandler`` on the root logger, which also -picks up griffe's "No type or annotation for parameter". That one reports a -*source* typing gap — a parameter the docstring describes but the signature does -not annotate — not a documentation defect, and it cannot be fixed from here -without inventing a type for a parameter whose accepted values have to be -established first. - -The filter is attached to the counting handler only, so the warning still prints -and stays visible; it just does not abort the build. Every other griffe or MkDocs -warning is still counted and still fails ``--strict``. Remove this hook once the -annotations land. -""" - -from __future__ import annotations - -import logging - -from mkdocs.utils import CountHandler - -_SUPPRESSED = "No type or annotation for parameter" - - -class _UncountMissingAnnotation(logging.Filter): - def filter(self, record: logging.LogRecord) -> bool: - return _SUPPRESSED not in record.getMessage() - - -def on_pre_build(config) -> None: # noqa: ANN001, ARG001 -- MkDocs hook signature - # Not on_startup: `build()` attaches the counter to the `mkdocs` logger at its - # own entry, which is after startup but before this event fires. - for handler in logging.getLogger("mkdocs").handlers: - if isinstance(handler, CountHandler): - handler.addFilter(_UncountMissingAnnotation()) diff --git a/mkdocs.yml b/mkdocs.yml index 76248b25c..ccdd39272 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,9 +27,25 @@ theme: scheme: slate toggle: { icon: material/weather-sunny, name: Switch to light mode } +# A page absent from nav builds fine by default and only shows up as an INFO +# line, so it silently disappears from the site's navigation. Promote it to a +# warning, which --strict then treats as a failure. +validation: + nav: + omitted_files: warn + not_found: warn + +# Deliberate omissions: these are accumulating logs and design sets, reached +# through their own index pages rather than the sidebar. Listing every entry in +# nav would bury the rest of the tree. Declaring them here keeps +# omitted_files strict for everything else. +not_in_nav: | + investigations/* + remote-l3-worker-design/* + troubleshooting/device-error-codes/* + hooks: - docs/_hooks/repo_links.py - - docs/_hooks/griffe_filter.py plugins: - search diff --git a/python/simpler/task_interface.py b/python/simpler/task_interface.py index 6e9d037d7..e29bec4c5 100644 --- a/python/simpler/task_interface.py +++ b/python/simpler/task_interface.py @@ -30,7 +30,13 @@ from enum import IntEnum from math import prod from pathlib import Path -from typing import Any +from typing import TYPE_CHECKING, Any + +if TYPE_CHECKING: + # Annotation-only: `CallableHandle` is imported lazily at its use site, and + # PEP 563 keeps these annotations as strings, so nothing is imported at + # runtime. + from .callable_identity import CallableHandle import _task_interface as _ti_module # pyright: ignore[reportMissingImports] from _task_interface import ( # pyright: ignore[reportMissingImports] @@ -1059,7 +1065,18 @@ def __init__(self): self._live_handles: dict[int, bytes] = {} self._next_handle_id = 0 - def init(self, device_id, bins, log_level=None, log_info_v=None, prewarm_config=None, enable_sdma=False): + def init( + self, + device_id: int, + # Structurally typed: any object exposing the *_path attributes below. + # Not RuntimeBinaries — that lives in simpler_setup, which this package + # must not depend on. + bins: Any, + log_level: int | None = None, + log_info_v: int | None = None, + prewarm_config: CallConfig | None = None, + enable_sdma: bool = False, + ): """Attach the calling thread to ``device_id``, load the host runtime library, and cache platform binaries. @@ -1253,7 +1270,13 @@ def register_callable(self, callable): raise return handle - def run(self, handle, args, config=None, **kwargs): + def run( + self, + handle: CallableHandle, + args: ChipStorageTaskArgs, + config: CallConfig | None = None, + **kwargs: Any, + ): """Launch a callable previously returned by ``register_callable``. Args: diff --git a/python/simpler/worker.py b/python/simpler/worker.py index b5d4be7b6..ed9a99e42 100644 --- a/python/simpler/worker.py +++ b/python/simpler/worker.py @@ -4208,7 +4208,7 @@ def _validate_eligible_targets(self) -> None: f"has no eligible dispatch target (needs {need})" ) - def init(self, prewarm_config=None, *, _startup_deadline: float | None = None) -> None: + def init(self, prewarm_config: CallConfig | None = None, *, _startup_deadline: float | None = None) -> None: """Initialize the worker and bring its whole subtree to READY. For an L3+ worker ``init`` is the single startup submission point: it