Auto-update Docs Reference section action (#13127)

Signed-off-by: Glenn Jocher <glenn.jocher@ultralytics.com> Co-authored-by: UltralyticsAssistant <web@ultralytics.com>
2025-09-15 15:48:41 +08:00 · 2024-05-25 21:25:51 +02:00 · 2024-05-25 21:25:51 +02:00 · 627453c26a
commit 627453c26a
parent 2e65e6fcb3
15 changed files with 116 additions and 37 deletions
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@ -43,6 +43,9 @@ jobs:
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref }}
+          fetch-depth: 0
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
@ -50,6 +53,20 @@ jobs:
          cache: "pip" # caching pip dependencies
      - name: Install Dependencies
        run: pip install tqdm mkdocs-material "mkdocstrings[python]" mkdocs-jupyter mkdocs-redirects mkdocs-ultralytics-plugin
+      - name: Update Docs Reference Section
+        run: python docs/build_reference.py
+      - name: Commit and Push Changes
+        run: |
+          git add .
+          git reset HEAD -- .github/workflows/  # workflow changes are not permitted with default token
+          if ! git diff --staged --quiet; then
+            git config --global user.name "UltralyticsAssistant"
+            git config --global user.email "web@ultralytics.com"
+            git commit -m "Auto-update Ultralytics Docs by https://ultralytics.com/actions"
+            git push
+          else
+            echo "No changes to commit"
+          fi
      - name: Build Docs and Check for Warnings
        run: python docs/build_docs.py

--- a/docs/build_reference.py
+++ b/docs/build_reference.py
@ -7,13 +7,13 @@ Note: Must be run from repository root directory. Do not run from docs directory
 """

 import re
+import subprocess
 from collections import defaultdict
 from pathlib import Path

-# Get package root i.e. /Users/glennjocher/PycharmProjects/ultralytics/ultralytics
-from ultralytics.utils import ROOT as PACKAGE_DIR
-
 # Constants
+FILE = Path(__file__).resolve()
+PACKAGE_DIR = FILE.parents[1] / "ultralytics"  # i.e. /Users/glennjocher/PycharmProjects/ultralytics/ultralytics
 REFERENCE_DIR = PACKAGE_DIR.parent / "docs/en/reference"
 GITHUB_REPO = "ultralytics/ultralytics"

@ -33,15 +33,18 @@ def extract_classes_and_functions(filepath: Path) -> tuple:
 def create_markdown(py_filepath: Path, module_path: str, classes: list, functions: list):
    """Creates a Markdown file containing the API reference for the given Python module."""
    md_filepath = py_filepath.with_suffix(".md")
+    exists = md_filepath.exists()

    # Read existing content and keep header content between first two ---
    header_content = ""
-    if md_filepath.exists():
+    if exists:
        existing_content = md_filepath.read_text()
        header_parts = existing_content.split("---")
        for part in header_parts:
            if "description:" in part or "comments:" in part:
                header_content += f"---{part}---\n\n"
+        if not any(header_content):
+            header_content = "---\ndescription: TODO ADD DESCRIPTION\nkeywords: TODO ADD KEYWORDS\n---\n\n"

    module_name = module_path.replace(".__init__", "")
    module_path = module_path.replace(".", "/")
@ -62,6 +65,11 @@ def create_markdown(py_filepath: Path, module_path: str, classes: list, function
    md_filepath.parent.mkdir(parents=True, exist_ok=True)
    md_filepath.write_text(md_content)

+    if not exists:
+        # Add new markdown file to the git staging area
+        print(f"Created new file '{md_filepath}'")
+        subprocess.run(["git", "add", "-f", str(md_filepath)], check=True)
+
    return md_filepath.relative_to(PACKAGE_DIR.parent)


--- a/docs/en/guides/parking-management.md
+++ b/docs/en/guides/parking-management.md
@ -44,6 +44,7 @@ Parking management with [Ultralytics YOLOv8](https://github.com/ultralytics/ultr

        ```python
        from ultralytics import solutions
+
        solutions.ParkingPtsSelection()
        ```

--- a/docs/en/index.md
+++ b/docs/en/index.md
@ -5,10 +5,38 @@ keywords: Ultralytics, YOLOv8, object detection, image segmentation, machine lea
 ---

 <div align="center">
-  <p>
-    <a href="https://github.com/ultralytics/assets/releases/tag/v8.2.0" target="_blank">
-    <img width="1024" src="https://raw.githubusercontent.com/ultralytics/assets/main/yolov8/banner-yolov8.png" alt="Ultralytics YOLO banner"></a>
-  </p>
+<a href="https://github.com/ultralytics/assets/releases/tag/v8.2.0" target="_blank"><img width="1024%" src="https://raw.githubusercontent.com/ultralytics/assets/main/yolov8/banner-yolov8.png" alt="Ultralytics YOLO banner"></a>
+<a href="https://docs.ultralytics.com/zh/">中文</a> |
+<a href="https://docs.ultralytics.com/ko/">한국어</a> |
+<a href="https://docs.ultralytics.com/ja/">日本語</a> |
+<a href="https://docs.ultralytics.com/ru/">Русский</a> |
+<a href="https://docs.ultralytics.com/de/">Deutsch</a> |
+<a href="https://docs.ultralytics.com/fr/">Français</a> |
+<a href="https://docs.ultralytics.com/es/">Español</a> |
+<a href="https://docs.ultralytics.com/pt/">Português</a> |
+<a href="https://docs.ultralytics.com/tr/">Türkçe</a> |
+<a href="https://docs.ultralytics.com/vi/">Tiếng Việt</a> |
+<a href="https://docs.ultralytics.com/hi/">हिन्दी</a> |
+<a href="https://docs.ultralytics.com/ar/">العربية</a>
+<br>
+<br>
+<a href="https://github.com/ultralytics/ultralytics/actions/workflows/ci.yaml"><img src="https://github.com/ultralytics/ultralytics/actions/workflows/ci.yaml/badge.svg" alt="Ultralytics CI"></a>
+<a href="https://codecov.io/github/ultralytics/ultralytics"><img src="https://codecov.io/github/ultralytics/ultralytics/branch/main/graph/badge.svg?token=HHW7IIVFVY" alt="Ultralytics Code Coverage"></a>
+<a href="https://zenodo.org/badge/latestdoi/264818686"><img src="https://zenodo.org/badge/264818686.svg" alt="YOLOv8 Citation"></a>
+<a href="https://hub.docker.com/r/ultralytics/ultralytics"><img src="https://img.shields.io/docker/pulls/ultralytics/ultralytics?logo=docker" alt="Docker Pulls"></a>
+<a href="https://ultralytics.com/discord"><img alt="Discord" src="https://img.shields.io/discord/1089800235347353640?logo=discord&logoColor=white&label=Discord&color=blue"></a>
+<br>
+<a href="https://console.paperspace.com/github/ultralytics/ultralytics"><img src="https://assets.paperspace.io/img/gradient-badge.svg" alt="Run on Gradient"></a>
+<a href="https://colab.research.google.com/github/ultralytics/ultralytics/blob/main/examples/tutorial.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"></a>
+<a href="https://www.kaggle.com/ultralytics/yolov8"><img src="https://kaggle.com/static/images/open-in-kaggle.svg" alt="Open In Kaggle"></a>
+</div>
+
+Introducing [Ultralytics](https://ultralytics.com) [YOLOv8](https://github.com/ultralytics/ultralytics), the latest version of the acclaimed real-time object detection and image segmentation model. YOLOv8 is built on cutting-edge advancements in deep learning and computer vision, offering unparalleled performance in terms of speed and accuracy. Its streamlined design makes it suitable for various applications and easily adaptable to different hardware platforms, from edge devices to cloud APIs.
+
+Explore the YOLOv8 Docs, a comprehensive resource designed to help you understand and utilize its features and capabilities. Whether you are a seasoned machine learning practitioner or new to the field, this hub aims to maximize YOLOv8's potential in your projects
+
+<div align="center">
+  <br>
  <a href="https://github.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-github.png" width="3%" alt="Ultralytics GitHub"></a>
  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
  <a href="https://www.linkedin.com/company/ultralytics/"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-linkedin.png" width="3%" alt="Ultralytics LinkedIn"></a>
@ -22,22 +50,8 @@ keywords: Ultralytics, YOLOv8, object detection, image segmentation, machine lea
  <a href="https://www.instagram.com/ultralytics/"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-instagram.png" width="3%" alt="Ultralytics Instagram"></a>
  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
  <a href="https://ultralytics.com/discord"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-discord.png" width="3%" alt="Ultralytics Discord"></a>
-  <br>
-  <br>
-  <a href="https://github.com/ultralytics/ultralytics/actions/workflows/ci.yaml"><img src="https://github.com/ultralytics/ultralytics/actions/workflows/ci.yaml/badge.svg" alt="Ultralytics CI"></a>
-  <a href="https://codecov.io/github/ultralytics/ultralytics"><img src="https://codecov.io/github/ultralytics/ultralytics/branch/main/graph/badge.svg?token=HHW7IIVFVY" alt="Ultralytics Code Coverage"></a>
-  <a href="https://zenodo.org/badge/latestdoi/264818686"><img src="https://zenodo.org/badge/264818686.svg" alt="YOLOv8 Citation"></a>
-  <a href="https://hub.docker.com/r/ultralytics/ultralytics"><img src="https://img.shields.io/docker/pulls/ultralytics/ultralytics?logo=docker" alt="Docker Pulls"></a>
-  <a href="https://ultralytics.com/discord"><img alt="Discord" src="https://img.shields.io/discord/1089800235347353640?logo=discord&logoColor=white&label=Discord&color=blue"></a>
-  <br>
-  <a href="https://console.paperspace.com/github/ultralytics/ultralytics"><img src="https://assets.paperspace.io/img/gradient-badge.svg" alt="Run on Gradient"></a>
-  <a href="https://colab.research.google.com/github/ultralytics/ultralytics/blob/main/examples/tutorial.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"></a>
-  <a href="https://www.kaggle.com/ultralytics/yolov8"><img src="https://kaggle.com/static/images/open-in-kaggle.svg" alt="Open In Kaggle"></a>
 </div>

-Introducing [Ultralytics](https://ultralytics.com) [YOLOv8](https://github.com/ultralytics/ultralytics), the latest version of the acclaimed real-time object detection and image segmentation model. YOLOv8 is built on cutting-edge advancements in deep learning and computer vision, offering unparalleled performance in terms of speed and accuracy. Its streamlined design makes it suitable for various applications and easily adaptable to different hardware platforms, from edge devices to cloud APIs.
-
-Explore the YOLOv8 Docs, a comprehensive resource designed to help you understand and utilize its features and capabilities. Whether you are a seasoned machine learning practitioner or new to the field, this hub aims to maximize YOLOv8's potential in your projects

 ## Where to Start

--- a/docs/en/reference/models/yolo/world/train.md
+++ b/docs/en/reference/models/yolo/world/train.md
@ -1,3 +1,8 @@
+---
+description: Detailed guide on the Ultralytics YOLO WorldTrainer class, including methods for fine-tuning world models and dataset building.
+keywords: Ultralytics, YOLO, WorldTrainer, WorldModel, training, dataset, machine learning, AI, deep learning, computer vision, ViT-B/32, clip
+---
+
 # Reference for `ultralytics/models/yolo/world/train.py`

 !!! Note
--- a/docs/en/reference/models/yolo/world/train_world.md
+++ b/docs/en/reference/models/yolo/world/train_world.md
@ -1,3 +1,8 @@
+---
+description: Comprehensive guide on the WorldTrainerFromScratch class for training YOLO world models from scratch on open-set datasets.
+keywords: YOLO, WorldTrainerFromScratch, Ultralytics, YOLO world models, open-set datasets, deep learning, machine learning, computer vision, dataset building, ViT-B/32, CLIP, training
+---
+
 # Reference for `ultralytics/models/yolo/world/train_world.py`

 !!! Note
--- a/docs/en/reference/solutions/analytics.md
+++ b/docs/en/reference/solutions/analytics.md
@ -0,0 +1,16 @@
+---
+description: This script integrates Ultralytics YOLO with OpenCV and Matplotlib to create and update line, bar, and pie charts for real-time data visualization in video processing.
+keywords: Ultralytics, YOLO, data visualization, OpenCV, Matplotlib, line chart, bar chart, pie chart, real-time analytics, video processing, machine learning, computer vision, AGPL-3.0
+---
+
+# Reference for `ultralytics/solutions/analytics.py`
+
+!!! Note
+
+    This file is available at [https://github.com/ultralytics/ultralytics/blob/main/ultralytics/solutions/analytics.py](https://github.com/ultralytics/ultralytics/blob/main/ultralytics/solutions/analytics.py). If you spot a problem please help fix it by [contributing](/help/contributing.md) a [Pull Request](https://github.com/ultralytics/ultralytics/edit/main/ultralytics/solutions/analytics.py) 🛠️. Thank you 🙏!
+
+<br><br>
+
+## ::: ultralytics.solutions.analytics.Analytics
+
+<br><br>
--- a/docs/mkdocs_github_authors.yaml
+++ b/docs/mkdocs_github_authors.yaml
@ -16,6 +16,7 @@
 78843978+Skillnoob@users.noreply.github.com: Skillnoob
 79740115+0xSynapse@users.noreply.github.com: 0xSynapse
 abirami.vina@gmail.com: abirami-vina
+andrei.kochin@intel.com: andrei-kochin
 ayush.chaurarsia@gmail.com: AyushExel
 chr043416@gmail.com: RizwanMunawar
 glenn.jocher@ultralytics.com: glenn-jocher
@ -28,4 +29,3 @@ priytosh.revolution@live.com: priytosh-tripathi
 shuizhuyuanluo@126.com: null
 stormsson@users.noreply.github.com: stormsson
 xinwang614@gmail.com: GreatV
-andrei.kochin@intel.com: andrei-kochin
--- a/examples/heatmaps.ipynb
+++ b/examples/heatmaps.ipynb
@ -50,7 +50,9 @@
      "source": [
        "# Setup\n",
        "\n",
-        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware."
+        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware.\n",
+        "\n",
+        "[![PyPI - Version](https://img.shields.io/pypi/v/ultralytics?logo=pypi&logoColor=white)](https://pypi.org/project/ultralytics/) [![Downloads](https://static.pepy.tech/badge/ultralytics)](https://pepy.tech/project/ultralytics) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ultralytics?logo=python&logoColor=gold)](https://pypi.org/project/ultralytics/)"
      ],
      "metadata": {
        "id": "o68Sg1oOeZm2"
--- a/examples/hub.ipynb
+++ b/examples/hub.ipynb
@ -49,7 +49,9 @@
      "source": [
        "# Setup\n",
        "\n",
-        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware."
+        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware.\n",
+        "\n",
+        "[![PyPI - Version](https://img.shields.io/pypi/v/ultralytics?logo=pypi&logoColor=white)](https://pypi.org/project/ultralytics/) [![Downloads](https://static.pepy.tech/badge/ultralytics)](https://pepy.tech/project/ultralytics) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ultralytics?logo=python&logoColor=gold)](https://pypi.org/project/ultralytics/)"
      ]
    },
    {
--- a/examples/object_counting.ipynb
+++ b/examples/object_counting.ipynb
@ -49,7 +49,9 @@
      "source": [
        "# Setup\n",
        "\n",
-        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware."
+        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware.\n",
+        "\n",
+        "[![PyPI - Version](https://img.shields.io/pypi/v/ultralytics?logo=pypi&logoColor=white)](https://pypi.org/project/ultralytics/) [![Downloads](https://static.pepy.tech/badge/ultralytics)](https://pepy.tech/project/ultralytics) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ultralytics?logo=python&logoColor=gold)](https://pypi.org/project/ultralytics/)"
      ],
      "metadata": {
        "id": "o68Sg1oOeZm2"
@ -203,4 +205,4 @@
      }
    }
  ]
-}
+}
--- a/examples/object_tracking.ipynb
+++ b/examples/object_tracking.ipynb
@ -49,7 +49,9 @@
      "source": [
        "# Setup\n",
        "\n",
-        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware."
+        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware.\n",
+        "\n",
+        "[![PyPI - Version](https://img.shields.io/pypi/v/ultralytics?logo=pypi&logoColor=white)](https://pypi.org/project/ultralytics/) [![Downloads](https://static.pepy.tech/badge/ultralytics)](https://pepy.tech/project/ultralytics) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ultralytics?logo=python&logoColor=gold)](https://pypi.org/project/ultralytics/)"
      ],
      "metadata": {
        "id": "o68Sg1oOeZm2"
@ -238,4 +240,4 @@
      }
    }
  ]
-}
+}
--- a/examples/tutorial.ipynb
+++ b/examples/tutorial.ipynb
@ -50,7 +50,9 @@
      "source": [
        "# Setup\n",
        "\n",
-        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware."
+        "Pip install `ultralytics` and [dependencies](https://github.com/ultralytics/ultralytics/blob/main/pyproject.toml) and check software and hardware.\n",
+        "\n",
+        "[![PyPI - Version](https://img.shields.io/pypi/v/ultralytics?logo=pypi&logoColor=white)](https://pypi.org/project/ultralytics/) [![Downloads](https://static.pepy.tech/badge/ultralytics)](https://pepy.tech/project/ultralytics) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ultralytics?logo=python&logoColor=gold)](https://pypi.org/project/ultralytics/)"
      ]
    },
    {
@ -67,7 +69,7 @@
        "import ultralytics\n",
        "ultralytics.checks()"
      ],
-      "execution_count": 1,
+      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
@ -103,7 +105,7 @@
        "# Run inference on an image with YOLOv8n\n",
        "!yolo predict model=yolov8n.pt source='https://ultralytics.com/images/zidane.jpg'"
      ],
-      "execution_count": 2,
+      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
@ -171,7 +173,7 @@
        "# Validate YOLOv8n on COCO8 val\n",
        "!yolo val model=yolov8n.pt data=coco8.yaml"
      ],
-      "execution_count": 3,
+      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
@ -250,7 +252,7 @@
        "# Train YOLOv8n on COCO8 for 3 epochs\n",
        "!yolo train model=yolov8n.pt data=coco8.yaml epochs=3 imgsz=640"
      ],
-      "execution_count": 4,
+      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
@ -384,7 +386,7 @@
        "id": "CYIjW4igCjqD",
        "outputId": "947e65cc-79c8-4713-bfd4-3139903ac05a"
      },
-      "execution_count": 5,
+      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -171,6 +171,8 @@ nav:
          - 🇫🇷&nbsp Français: https://docs.ultralytics.com/fr/
          - 🇪🇸&nbsp Español: https://docs.ultralytics.com/es/
          - 🇵🇹&nbsp Português: https://docs.ultralytics.com/pt/
+          - 🇹🇷&nbsp Türkçe: https://docs.ultralytics.com/tr/
+          - 🇻🇳&nbsp Tiếng Việt: https://docs.ultralytics.com/vi/
          - 🇮🇳&nbsp हिन्दी: https://docs.ultralytics.com/hi/
          - 🇸🇦&nbsp العربية: https://docs.ultralytics.com/ar/
  - Quickstart:
@ -499,6 +501,7 @@ nav:
          - tasks: reference/nn/tasks.md
      - solutions:
          - ai_gym: reference/solutions/ai_gym.md
+          - analytics: reference/solutions/analytics.md
          - distance_calculation: reference/solutions/distance_calculation.md
          - heatmap: reference/solutions/heatmap.md
          - object_counter: reference/solutions/object_counter.md
--- a/ultralytics/solutions/analytics.py
+++ b/ultralytics/solutions/analytics.py
@ -33,7 +33,7 @@ class Analytics:

        Args:
            type (str): Type of chart to initialize ('line', 'bar', or 'pie').
-            writer: Video writer object to save the frames.
+            writer (object): Video writer object to save the frames.
            im0_shape (tuple): Shape of the input image (width, height).
            title (str): Title of the chart.
            x_label (str): Label for the x-axis.
@ -64,7 +64,7 @@ class Analytics:
            self.ax = fig.add_subplot(111, facecolor=self.bg_color)
            (self.line,) = self.ax.plot([], [], color=line_color, linewidth=line_width)

-        elif type == "bar" or type == "pie":
+        elif type in {"bar", "pie"}:
            # Initialize bar or pie plot
            self.fig, self.ax = plt.subplots(figsize=figsize, facecolor=self.bg_color)
            self.ax.set_facecolor(self.bg_color)