Build reference for missing `__init__.py` files (#3227)

docs/build_reference.py

@@ -42,6 +42,7 @@ def create_markdown(py_filepath, module_path, classes, functions):
             if len(header_parts) >= 3:
                 header_content = f"{header_parts[0]}---{header_parts[1]}---\n\n"
 
+    module_path = module_path.replace('.__init__', '')
     md_content = [f"# {class_name}\n---\n:::{module_path}.{class_name}\n<br><br>\n" for class_name in classes]
     md_content.extend(f"# {func_name}\n---\n:::{module_path}.{func_name}\n<br><br>\n" for func_name in functions)
     md_content = header_content + "\n".join(md_content)
@@ -98,7 +99,7 @@ def main():
     nav_items = []
     for root, _, files in os.walk(CODE_DIR):
         for file in files:
-            if file.endswith(".py") and file != "__init__.py":
+            if file.endswith(".py"):
                 py_filepath = Path(root) / file
                 classes, functions = extract_classes_and_functions(py_filepath)
 

docs/reference/hub/__init__.md

@@ -0,0 +1,44 @@
+---
+description: Access Ultralytics HUB, manage API keys, train models, and export in various formats with ease using the HUB API.
+keywords: Ultralytics, YOLO, Docs HUB, API, login, logout, reset model, export model, check dataset, HUBDatasetStats, YOLO training, YOLO model
+---
+
+# login
+---
+:::ultralytics.hub.login
+<br><br>
+
+# logout
+---
+:::ultralytics.hub.logout
+<br><br>
+
+# start
+---
+:::ultralytics.hub.start
+<br><br>
+
+# reset_model
+---
+:::ultralytics.hub.reset_model
+<br><br>
+
+# export_fmts_hub
+---
+:::ultralytics.hub.export_fmts_hub
+<br><br>
+
+# export_model
+---
+:::ultralytics.hub.export_model
+<br><br>
+
+# get_export
+---
+:::ultralytics.hub.get_export
+<br><br>
+
+# check_dataset
+---
+:::ultralytics.hub.check_dataset
+<br><br>

docs/reference/yolo/cfg/__init__.md

@@ -0,0 +1,49 @@
+---
+description: Explore Ultralytics YOLO's configuration functions and tools. Handle settings, manage defaults, and deal with deprecations in your YOLO configuration.
+keywords: Ultralytics, YOLO, configuration, cfg2dict, get_cfg, handle_deprecation, check_cfg_mismatch, merge_equals_args, handle_yolo_hub, handle_yolo_settings, entrypoint, copy_default_cfg
+---
+
+# cfg2dict
+---
+:::ultralytics.yolo.cfg.cfg2dict
+<br><br>
+
+# get_cfg
+---
+:::ultralytics.yolo.cfg.get_cfg
+<br><br>
+
+# _handle_deprecation
+---
+:::ultralytics.yolo.cfg._handle_deprecation
+<br><br>
+
+# check_cfg_mismatch
+---
+:::ultralytics.yolo.cfg.check_cfg_mismatch
+<br><br>
+
+# merge_equals_args
+---
+:::ultralytics.yolo.cfg.merge_equals_args
+<br><br>
+
+# handle_yolo_hub
+---
+:::ultralytics.yolo.cfg.handle_yolo_hub
+<br><br>
+
+# handle_yolo_settings
+---
+:::ultralytics.yolo.cfg.handle_yolo_settings
+<br><br>
+
+# entrypoint
+---
+:::ultralytics.yolo.cfg.entrypoint
+<br><br>
+
+# copy_default_cfg
+---
+:::ultralytics.yolo.cfg.copy_default_cfg
+<br><br>

docs/reference/yolo/utils/__init__.md

@@ -0,0 +1,169 @@
+---
+description: Uncover utility functions in Ultralytics YOLO. Handle YAML, threading, logging, error-checking, and platform identification. Enhance your YOLO development process.
+keywords: Ultralytics, YOLO, utils, SimpleClass, IterableSimpleNamespace, EmojiFilter, TryExcept, plt_settings, set_logging, emojis, yaml_save, yaml_load, yaml_print, is_colab, is_kaggle, is_jupyter, is_docker, is_online, is_pip_package, is_dir_writeable, is_pytest_running, is_github_actions_ci, is_git_dir, get_git_dir, get_git_origin_url, get_git_branch, get_default_args, get_user_config_dir, colorstr, threaded, set_sentry, get_settings, set_settings, deprecation_warn, clean_url, url2file
+---
+
+# SimpleClass
+---
+:::ultralytics.yolo.utils.SimpleClass
+<br><br>
+
+# IterableSimpleNamespace
+---
+:::ultralytics.yolo.utils.IterableSimpleNamespace
+<br><br>
+
+# EmojiFilter
+---
+:::ultralytics.yolo.utils.EmojiFilter
+<br><br>
+
+# TryExcept
+---
+:::ultralytics.yolo.utils.TryExcept
+<br><br>
+
+# plt_settings
+---
+:::ultralytics.yolo.utils.plt_settings
+<br><br>
+
+# set_logging
+---
+:::ultralytics.yolo.utils.set_logging
+<br><br>
+
+# emojis
+---
+:::ultralytics.yolo.utils.emojis
+<br><br>
+
+# yaml_save
+---
+:::ultralytics.yolo.utils.yaml_save
+<br><br>
+
+# yaml_load
+---
+:::ultralytics.yolo.utils.yaml_load
+<br><br>
+
+# yaml_print
+---
+:::ultralytics.yolo.utils.yaml_print
+<br><br>
+
+# is_colab
+---
+:::ultralytics.yolo.utils.is_colab
+<br><br>
+
+# is_kaggle
+---
+:::ultralytics.yolo.utils.is_kaggle
+<br><br>
+
+# is_jupyter
+---
+:::ultralytics.yolo.utils.is_jupyter
+<br><br>
+
+# is_docker
+---
+:::ultralytics.yolo.utils.is_docker
+<br><br>
+
+# is_online
+---
+:::ultralytics.yolo.utils.is_online
+<br><br>
+
+# is_pip_package
+---
+:::ultralytics.yolo.utils.is_pip_package
+<br><br>
+
+# is_dir_writeable
+---
+:::ultralytics.yolo.utils.is_dir_writeable
+<br><br>
+
+# is_pytest_running
+---
+:::ultralytics.yolo.utils.is_pytest_running
+<br><br>
+
+# is_github_actions_ci
+---
+:::ultralytics.yolo.utils.is_github_actions_ci
+<br><br>
+
+# is_git_dir
+---
+:::ultralytics.yolo.utils.is_git_dir
+<br><br>
+
+# get_git_dir
+---
+:::ultralytics.yolo.utils.get_git_dir
+<br><br>
+
+# get_git_origin_url
+---
+:::ultralytics.yolo.utils.get_git_origin_url
+<br><br>
+
+# get_git_branch
+---
+:::ultralytics.yolo.utils.get_git_branch
+<br><br>
+
+# get_default_args
+---
+:::ultralytics.yolo.utils.get_default_args
+<br><br>
+
+# get_user_config_dir
+---
+:::ultralytics.yolo.utils.get_user_config_dir
+<br><br>
+
+# colorstr
+---
+:::ultralytics.yolo.utils.colorstr
+<br><br>
+
+# threaded
+---
+:::ultralytics.yolo.utils.threaded
+<br><br>
+
+# set_sentry
+---
+:::ultralytics.yolo.utils.set_sentry
+<br><br>
+
+# get_settings
+---
+:::ultralytics.yolo.utils.get_settings
+<br><br>
+
+# set_settings
+---
+:::ultralytics.yolo.utils.set_settings
+<br><br>
+
+# deprecation_warn
+---
+:::ultralytics.yolo.utils.deprecation_warn
+<br><br>
+
+# clean_url
+---
+:::ultralytics.yolo.utils.clean_url
+<br><br>
+
+# url2file
+---
+:::ultralytics.yolo.utils.url2file
+<br><br>

mkdocs.yml

@@ -249,6 +249,7 @@ nav:
       - Inference API: hub/inference_api.md
   - Reference:
       - hub:
+          - __init__: reference/hub/__init__.md
           - auth: reference/hub/auth.md
           - session: reference/hub/session.md
           - utils: reference/hub/utils.md
@@ -256,8 +257,8 @@ nav:
           - autobackend: reference/nn/autobackend.md
           - autoshape: reference/nn/autoshape.md
           - modules:
-              - blocks: reference/nn/modules/block.md
-              - convs: reference/nn/modules/conv.md
+              - block: reference/nn/modules/block.md
+              - conv: reference/nn/modules/conv.md
               - head: reference/nn/modules/head.md
               - transformer: reference/nn/modules/transformer.md
               - utils: reference/nn/modules/utils.md
@@ -273,6 +274,8 @@ nav:
               - kalman_filter: reference/tracker/utils/kalman_filter.md
               - matching: reference/tracker/utils/matching.md
       - yolo:
+          - cfg:
+              - __init__: reference/yolo/cfg/__init__.md
           - data:
               - annotator: reference/yolo/data/annotator.md
               - augment: reference/yolo/data/augment.md
@@ -298,6 +301,7 @@ nav:
               - predict: reference/yolo/nas/predict.md
               - val: reference/yolo/nas/val.md
           - utils:
+              - __init__: reference/yolo/utils/__init__.md
               - autobatch: reference/yolo/utils/autobatch.md
               - benchmarks: reference/yolo/utils/benchmarks.md
               - callbacks:
@@ -341,6 +345,7 @@ nav:
                   - predict: reference/yolo/v8/segment/predict.md
                   - train: reference/yolo/v8/segment/train.md
                   - val: reference/yolo/v8/segment/val.md
+
   - Help:
       - Help: help/index.md
       - Frequently Asked Questions (FAQ): help/FAQ.md

ultralytics/yolo/utils/__init__.py

@@ -177,7 +177,8 @@ def plt_settings(rcparams=None, backend='Agg'):
         backend (str, optional): Name of the backend to use. Defaults to 'Agg'.
 
     Returns:
-        callable: Decorated function with temporarily set rc parameters and backend.
+        (Callable): Decorated function with temporarily set rc parameters and backend. This decorator can be
+            applied to any function that needs to have specific matplotlib rc parameters and backend for its execution.
     """
 
     if rcparams is None:
@@ -259,7 +260,7 @@ def yaml_save(file='data.yaml', data=None):
         data (dict): Data to save in YAML format.
 
     Returns:
-        None: Data is saved to the specified file.
+        (None): Data is saved to the specified file.
     """
     if data is None:
         data = {}
@@ -287,7 +288,7 @@ def yaml_load(file='data.yaml', append_filename=False):
         append_filename (bool): Add the YAML filename to the YAML dictionary. Default is False.
 
     Returns:
-        dict: YAML data and file name.
+        (dict): YAML data and file name.
     """
     with open(file, errors='ignore', encoding='utf-8') as f:
         s = f.read()  # string
@@ -329,7 +330,7 @@ def is_colab():
     Check if the current script is running inside a Google Colab notebook.
 
     Returns:
-        bool: True if running inside a Colab notebook, False otherwise.
+        (bool): True if running inside a Colab notebook, False otherwise.
     """
     return 'COLAB_RELEASE_TAG' in os.environ or 'COLAB_BACKEND_VERSION' in os.environ
 
@@ -339,7 +340,7 @@ def is_kaggle():
     Check if the current script is running inside a Kaggle kernel.
 
     Returns:
-        bool: True if running inside a Kaggle kernel, False otherwise.
+        (bool): True if running inside a Kaggle kernel, False otherwise.
     """
     return os.environ.get('PWD') == '/kaggle/working' and os.environ.get('KAGGLE_URL_BASE') == 'https://www.kaggle.com'
 
@@ -350,7 +351,7 @@ def is_jupyter():
     Verified on Colab, Jupyterlab, Kaggle, Paperspace.
 
     Returns:
-        bool: True if running inside a Jupyter Notebook, False otherwise.
+        (bool): True if running inside a Jupyter Notebook, False otherwise.
     """
     with contextlib.suppress(Exception):
         from IPython import get_ipython
@@ -363,7 +364,7 @@ def is_docker() -> bool:
     Determine if the script is running inside a Docker container.
 
     Returns:
-        bool: True if the script is running inside a Docker container, False otherwise.
+        (bool): True if the script is running inside a Docker container, False otherwise.
     """
     file = Path('/proc/self/cgroup')
     if file.exists():
@@ -378,7 +379,7 @@ def is_online() -> bool:
     Check internet connectivity by attempting to connect to a known online host.
 
     Returns:
-        bool: True if connection is successful, False otherwise.
+        (bool): True if connection is successful, False otherwise.
     """
     import socket
 
@@ -405,7 +406,7 @@ def is_pip_package(filepath: str = __name__) -> bool:
         filepath (str): The filepath to check.
 
     Returns:
-        bool: True if the file is part of a pip package, False otherwise.
+        (bool): True if the file is part of a pip package, False otherwise.
     """
     import importlib.util
 
@@ -424,7 +425,7 @@ def is_dir_writeable(dir_path: Union[str, Path]) -> bool:
         dir_path (str) or (Path): The path to the directory.
 
     Returns:
-        bool: True if the directory is writeable, False otherwise.
+        (bool): True if the directory is writeable, False otherwise.
     """
     return os.access(str(dir_path), os.W_OK)
 
@@ -509,7 +510,7 @@ def get_default_args(func):
         func (callable): The function to inspect.
 
     Returns:
-        dict: A dictionary where each key is a parameter name, and each value is the default value of that parameter.
+        (dict): A dictionary where each key is a parameter name, and each value is the default value of that parameter.
     """
     signature = inspect.signature(func)
     return {k: v.default for k, v in signature.parameters.items() if v.default is not inspect.Parameter.empty}
@@ -523,7 +524,7 @@ def get_user_config_dir(sub_dir='Ultralytics'):
         sub_dir (str): The name of the subdirectory to create.
 
     Returns:
-        Path: The path to the user config directory.
+        (Path): The path to the user config directory.
     """
     # Return the appropriate config directory for each operating system
     if WINDOWS:
@@ -690,7 +691,7 @@ def get_settings(file=SETTINGS_YAML, version='0.0.3'):
         version (str): Settings version. If min settings version not met, new default settings will be saved.
 
     Returns:
-        dict: Dictionary of settings key-value pairs.
+        (dict): Dictionary of settings key-value pairs.
     """
     import hashlib