ultralytics 8.3.231

v8.3.231 - `ultralytics 8.3.231` New Zensical docs refresh (#22761)

on Python PyPI

🌟 Summary

v8.3.231 is a docs and tooling–focused release 🚀 that introduces a new Zensical-powered documentation pipeline with rich API reference pages, better HTML post-processing, and multiple reliability and usability improvements—without changing core YOLO11 model behavior.

📊 Key Changes

• 📚 New Zensical documentation engine (major)

  • Switched docs build from mkdocs build to zensical build with a revamped docs/build_docs.py.
  • Introduced a new build_reference_docs pipeline that:
    • Parses Python source (AST) and Google-style docstrings.
    • Pre-renders structured API reference markdown (classes, methods, properties, functions, signatures, tables, source snippets).
  • Added visual doc-kind badges (Class / Method / Function / Property) and cleaned up titles, links, and code line-number markup.
  • Post-processes the built site with mkdocs-ultralytics-plugin for better metadata, JSON-LD, authors, and social cards.

• 🧩 MiniJinja-based docs macros (templating refresh)

  • Replaced the old MkDocs macros plugin with a MiniJinja pre-render pass (render_jinja_macros).
  • Macros now render directly into markdown before the docs build, using:
    • mkdocs.yml extra values,
    • ultralytics/cfg/default.yaml,
    • A custom indent filter to stay compatible with existing macros.
  • Docs sources (docs/en, docs/macros) are backed up and restored around the build to keep the repo clean.

• 🧱 Reference docs re-architecture

  • docs/build_reference.py rewritten to:
    • Build fully structured reference pages from AST + docstrings (not just mkdocstrings stubs).
    • Merge __init__ docstring info into class docs intelligently (no runtime behavior changes).
    • Generate per-item sections: Args, Returns, Attributes, Notes, Examples, Raises, and tables for parameters/returns.
    • Include collapsible “View on GitHub” source panels with line-number deep links.
  • Supports building references for external packages like hub-sdk (Ultralytics HUB SDK).

• 🎨 Docs UX & content polish

  • Refreshed docs landing page layout, language selector, and YOLO11 intro text.
  • Standardized CUDA links from /cuda-zone → /cuda.
  • Updated DVCLive links to the new doc.dvc.org domain.
  • Fixed FastSAM links to the correct CASIA-LMC-Lab/FastSAM repository.
  • Ensured proper admonition formatting (!!! note, !!! warning) so they render reliably.
  • Replaced Jinja include syntax in performance tables with --8<-- "docs/macros/..." includes, consistent with the new macro pipeline.

• ⚙️ Settings & concurrency reliability

  • Updated SettingsManager._load to call super().update(...) instead of self.update(...).
  • Prevents unintended writes or side effects during config file reads, reducing race-condition risks when multiple instances run in parallel. 🔒

• 🍎 Apple MPS & metrics cleanup

  • Removed obsolete MPS warnings for pose models (bug no longer present) to reduce noise for Apple Silicon users.
  • Standardized OKS_SIGMA to float32 in metrics for more consistent pose evaluation behavior.

• 🖼️ Data format documentation clarification

  • COCO8-Multispectral docs now explicitly require TIFF/TIF images to be uint8, in addition to (channel, height, width) layout and .tiff/.tif extensions. Prevents subtle runtime issues when preparing multispectral data. 🌈

• 💻 Windows workflow documentation

  • Training (train.md) and validation (val.md) docs now:
    • Call out the common “Windows multi-processing RuntimeError”.
    • Instruct users to wrap script entry points with:

      if __name__ == "__main__":
          ...

    • Helps Windows users avoid confusing crashes when running YOLO11 scripts. 🪟

• 🧹 Docstring cleanup for codebase

  • Removed redundant Examples: and Attributes: blocks from many class __init__ docstrings.
  • Consolidated notes (e.g., Albumentations requirements and behavior).
  • Makes docstrings more maintainable and better suited to the new automatic reference renderer.

• 🧾 Tooling & repo hygiene

  • Bumped mkdocs-ultralytics-plugin dev dependency to >=0.2.2 to support the new docs flow.
  • Added uv.lock to .gitignore to avoid committing local UV lock files.
  • Dropped an unnecessary JUPYTER_PLATFORM_DIRS export from the docs CI workflow.

🎯 Purpose & Impact

• 🧠 Richer, easier-to-navigate API docs

  • Users get first-class API references: clear signatures, parameter tables, return types, examples, and source links directly in the docs.
  • The new doc-kind badges and navigation improvements make it easier to discover what’s a class, method, function, or property at a glance.

• 🛠️ More robust and maintainable docs pipeline

  • AST-based doc generation and MiniJinja pre-rendering remove reliance on heavy MkDocs/mkdocstrings plugin magic.
  • Backups + deterministic builds mean contributors can safely iterate on docs without polluting sources or fighting fragile configs.

• 🔒 Safer multi-process / multi-instance usage

  • Fixing SettingsManager read behavior reduces the chance of config corruption or race conditions when multiple processes touch settings simultaneously.

• 💻 Smoother platform-specific experiences

  • Windows users get clearer guidance to avoid multi-processing errors.
  • Apple Silicon users no longer see outdated MPS pose warnings, improving trust and reducing noise.

• 🛰️ Fewer user mistakes with advanced data / integrations

  • Stricter TIFF uint8 guidance prevents subtle multispectral dataset bugs.
  • Updated CUDA, DVCLive, and FastSAM links keep users on current, supported resources.

• ✅ No breaking changes to YOLO11 models

  • Core training, inference, and export behavior remain unchanged.
  • This release is safe to adopt if you rely on existing YOLO11 workflows; you mainly gain better docs and more robust tooling.

What's Changed

• Replace MkDocs macros with minijinja by @glenn-jocher in #22749
• Clarify TIFF/TIF images must be uint8 by @Y-T-G in #22756
• Document Windows RuntimeError workaround by @Y-T-G in #22755
• Update "mkdocs-ultralytics-plugin>=0.2.2" by @glenn-jocher in #22757
• Remove Class init examples by @glenn-jocher in #22759
• Update SettingsManager to avoid race conditions in parallel instances by @glenn-jocher in #22762
• chore: 🧹 update .gitignore to include uv.lock by @onuralpszr in #22766
• Fix admonitions and 301s by @glenn-jocher in #22767
• Remove MPS warnings for pose models by @Y-T-G in #22753
• ultralytics 8.3.231 New Zensical docs refresh by @glenn-jocher in #22761

Full Changelog: v8.3.230...v8.3.231