Auto-update Docs Reference section action (#13127)

Signed-off-by: Glenn Jocher <glenn.jocher@ultralytics.com>
Co-authored-by: UltralyticsAssistant <web@ultralytics.com>

.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
 

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)
 
 

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()
         ```
 

docs/en/index.md

@@ -5,23 +5,19 @@ 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>
-    <a href="https://github.com/ultralytics/assets/releases/tag/v8.2.0" target="_blank">
+<a href="https://docs.ultralytics.com/zh/">中文</a> |
-    <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/ko/">한국어</a> |
-  </p>
+<a href="https://docs.ultralytics.com/ja/">日本語</a> |
-  <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>
+<a href="https://docs.ultralytics.com/ru/">Русский</a> |
-  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
+<a href="https://docs.ultralytics.com/de/">Deutsch</a> |
-  <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>
+<a href="https://docs.ultralytics.com/fr/">Français</a> |
-  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
+<a href="https://docs.ultralytics.com/es/">Español</a> |
-  <a href="https://twitter.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-twitter.png" width="3%" alt="Ultralytics Twitter"></a>
+<a href="https://docs.ultralytics.com/pt/">Português</a> |
-  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
+<a href="https://docs.ultralytics.com/tr/">Türkçe</a> |
-  <a href="https://youtube.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
+<a href="https://docs.ultralytics.com/vi/">Tiếng Việt</a> |
-  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
+<a href="https://docs.ultralytics.com/hi/">हिन्दी</a> |
-  <a href="https://www.tiktok.com/@ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-tiktok.png" width="3%" alt="Ultralytics TikTok"></a>
+<a href="https://docs.ultralytics.com/ar/">العربية</a>
-  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
-  <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>
@@ -39,6 +35,24 @@ Introducing [Ultralytics](https://ultralytics.com) [YOLOv8](https://github.com/u
 
 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>
+  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
+  <a href="https://twitter.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-twitter.png" width="3%" alt="Ultralytics Twitter"></a>
+  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
+  <a href="https://youtube.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
+  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
+  <a href="https://www.tiktok.com/@ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-tiktok.png" width="3%" alt="Ultralytics TikTok"></a>
+  <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
+  <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>
+</div>
+
+
 ## Where to Start
 
 - **Install** `ultralytics` with pip and get up and running in minutes &nbsp; [:material-clock-fast: Get Started](quickstart.md){ .md-button }

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

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

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>

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

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"

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/)"
       ]
     },
     {

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"

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"

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",

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

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)