From 03bce0784827f52ac602fdad83c68123f416bc35 Mon Sep 17 00:00:00 2001 From: Glenn Jocher Date: Sat, 17 Jun 2023 13:31:46 +0200 Subject: [PATCH] Build reference for missing `__init__.py` files (#3227) --- docs/build_reference.py | 3 +- docs/reference/hub/__init__.md | 44 +++++++ docs/reference/yolo/cfg/__init__.md | 49 ++++++++ docs/reference/yolo/utils/__init__.md | 169 ++++++++++++++++++++++++++ mkdocs.yml | 9 +- ultralytics/yolo/utils/__init__.py | 27 ++-- 6 files changed, 285 insertions(+), 16 deletions(-) create mode 100644 docs/reference/hub/__init__.md create mode 100644 docs/reference/yolo/cfg/__init__.md create mode 100644 docs/reference/yolo/utils/__init__.md diff --git a/docs/build_reference.py b/docs/build_reference.py index b75822a..86dd409 100644 --- a/docs/build_reference.py +++ b/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

\n" for class_name in classes] md_content.extend(f"# {func_name}\n---\n:::{module_path}.{func_name}\n

\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) diff --git a/docs/reference/hub/__init__.md b/docs/reference/hub/__init__.md new file mode 100644 index 0000000..1d75102 --- /dev/null +++ b/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 +

+ +# logout +--- +:::ultralytics.hub.logout +

+ +# start +--- +:::ultralytics.hub.start +

+ +# reset_model +--- +:::ultralytics.hub.reset_model +

+ +# export_fmts_hub +--- +:::ultralytics.hub.export_fmts_hub +

+ +# export_model +--- +:::ultralytics.hub.export_model +

+ +# get_export +--- +:::ultralytics.hub.get_export +

+ +# check_dataset +--- +:::ultralytics.hub.check_dataset +

diff --git a/docs/reference/yolo/cfg/__init__.md b/docs/reference/yolo/cfg/__init__.md new file mode 100644 index 0000000..103ecad --- /dev/null +++ b/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 +

+ +# get_cfg +--- +:::ultralytics.yolo.cfg.get_cfg +

+ +# _handle_deprecation +--- +:::ultralytics.yolo.cfg._handle_deprecation +

+ +# check_cfg_mismatch +--- +:::ultralytics.yolo.cfg.check_cfg_mismatch +

+ +# merge_equals_args +--- +:::ultralytics.yolo.cfg.merge_equals_args +

+ +# handle_yolo_hub +--- +:::ultralytics.yolo.cfg.handle_yolo_hub +

+ +# handle_yolo_settings +--- +:::ultralytics.yolo.cfg.handle_yolo_settings +

+ +# entrypoint +--- +:::ultralytics.yolo.cfg.entrypoint +

+ +# copy_default_cfg +--- +:::ultralytics.yolo.cfg.copy_default_cfg +

diff --git a/docs/reference/yolo/utils/__init__.md b/docs/reference/yolo/utils/__init__.md new file mode 100644 index 0000000..d54da17 --- /dev/null +++ b/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 +

+ +# IterableSimpleNamespace +--- +:::ultralytics.yolo.utils.IterableSimpleNamespace +

+ +# EmojiFilter +--- +:::ultralytics.yolo.utils.EmojiFilter +

+ +# TryExcept +--- +:::ultralytics.yolo.utils.TryExcept +

+ +# plt_settings +--- +:::ultralytics.yolo.utils.plt_settings +

+ +# set_logging +--- +:::ultralytics.yolo.utils.set_logging +

+ +# emojis +--- +:::ultralytics.yolo.utils.emojis +

+ +# yaml_save +--- +:::ultralytics.yolo.utils.yaml_save +

+ +# yaml_load +--- +:::ultralytics.yolo.utils.yaml_load +

+ +# yaml_print +--- +:::ultralytics.yolo.utils.yaml_print +

+ +# is_colab +--- +:::ultralytics.yolo.utils.is_colab +

+ +# is_kaggle +--- +:::ultralytics.yolo.utils.is_kaggle +

+ +# is_jupyter +--- +:::ultralytics.yolo.utils.is_jupyter +

+ +# is_docker +--- +:::ultralytics.yolo.utils.is_docker +

+ +# is_online +--- +:::ultralytics.yolo.utils.is_online +

+ +# is_pip_package +--- +:::ultralytics.yolo.utils.is_pip_package +

+ +# is_dir_writeable +--- +:::ultralytics.yolo.utils.is_dir_writeable +

+ +# is_pytest_running +--- +:::ultralytics.yolo.utils.is_pytest_running +

+ +# is_github_actions_ci +--- +:::ultralytics.yolo.utils.is_github_actions_ci +

+ +# is_git_dir +--- +:::ultralytics.yolo.utils.is_git_dir +

+ +# get_git_dir +--- +:::ultralytics.yolo.utils.get_git_dir +

+ +# get_git_origin_url +--- +:::ultralytics.yolo.utils.get_git_origin_url +

+ +# get_git_branch +--- +:::ultralytics.yolo.utils.get_git_branch +

+ +# get_default_args +--- +:::ultralytics.yolo.utils.get_default_args +

+ +# get_user_config_dir +--- +:::ultralytics.yolo.utils.get_user_config_dir +

+ +# colorstr +--- +:::ultralytics.yolo.utils.colorstr +

+ +# threaded +--- +:::ultralytics.yolo.utils.threaded +

+ +# set_sentry +--- +:::ultralytics.yolo.utils.set_sentry +

+ +# get_settings +--- +:::ultralytics.yolo.utils.get_settings +

+ +# set_settings +--- +:::ultralytics.yolo.utils.set_settings +

+ +# deprecation_warn +--- +:::ultralytics.yolo.utils.deprecation_warn +

+ +# clean_url +--- +:::ultralytics.yolo.utils.clean_url +

+ +# url2file +--- +:::ultralytics.yolo.utils.url2file +

diff --git a/mkdocs.yml b/mkdocs.yml index 5f3a6c1..b6930aa 100644 --- a/mkdocs.yml +++ b/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 diff --git a/ultralytics/yolo/utils/__init__.py b/ultralytics/yolo/utils/__init__.py index 1751395..75361c8 100644 --- a/ultralytics/yolo/utils/__init__.py +++ b/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