Update README (#1)

.github/workflows/ruff.yml

@@ -0,0 +1,34 @@
+# Ultralytics 🚀, AGPL-3.0 license
+# Ruff formatting action https://github.com/astral-sh/ruff
+
+name: Ruff Format
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install Ruff
+        run: pip install ruff
+      - name: Run Ruff Format
+        run: ruff format .
+      - name: Commit and Push Changes
+        run: |
+          git config --global user.name "glenn-jocher"
+          git config --global user.email "glenn.jocher@ultralytics.com"
+          git add -A
+          git commit -m "Apply ruff formatting" || echo "No changes to commit"
+          git push

README.md

@@ -22,6 +22,27 @@ The repository is meticulously organized to offer intuitive navigation and a cle
 - `setup.py`: (Optional, if using PyPI) Details for packaging and distributing the project.
 - Linting and formatting configuration files (like `.flake8`, `.pylintrc`, `pyproject.toml`).
 
+```
+your-project/
+│
+├── your_package_name/
+│   ├── __init__.py
+│   ├── module1.py
+│   ├── module2.py
+│   └── ...
+│
+├── tests/
+│   ├── __init__.py
+│   ├── test_module1.py
+│   └── ...
+│
+├── docs/
+│   └── ...
+│
+├── pyproject.toml
+└── README.md
+```
+
 ### Source Code in `src/` Directory 📂
 
 The `src/` directory is the heart of your project, containing the Python code that constitutes your package. This structure encourages clean imports and testing practices.

docs/README.md

@@ -0,0 +1,21 @@
+<br>
+<img src="https://raw.githubusercontent.com/ultralytics/assets/main/logo/Ultralytics_Logotype_Original.svg" width="320">
+
+# Documentation Directory (`docs/`)
+
+This directory contains the documentation for our project, managed with MkDocs.
+
+## Overview
+
+- **MkDocs Configuration:** The configuration file for MkDocs is `mkdocs.yml`. It defines the structure and settings of our project documentation.
+- **Documentation Files:** Written in Markdown, these files reside in this directory and are structured according to the MkDocs configuration.
+
+## Getting Started
+
+To work with the documentation:
+
+1. **Install MkDocs:** Ensure MkDocs is installed in your environment.
+2. **Preview Documentation:** Run `mkdocs serve` to start a local server and preview the documentation in your browser.
+3. **Build Documentation:** Use `mkdocs build` to generate the static site.
+
+The documentation should be kept up-to-date with the project's development, ensuring clarity and usefulness for both internal developers and external users.

pyproject.toml

@@ -0,0 +1,82 @@
+# Ultralytics Template 🚀, AGPL-3.0 license
+#
+# Overview:
+# This pyproject.toml file manages the build, packaging, and distribution of the Ultralytics Template library.
+# It defines essential project metadata, dependencies, and settings used to develop and deploy the library.
+
+# Key Sections:
+# - [build-system]: Specifies the build requirements and backend (e.g., setuptools, wheel).
+# - [project]: Includes details like name, version, description, authors, dependencies and more.
+# - [project.optional-dependencies]: Provides additional, optional packages for extended features.
+# - [tool.*]: Configures settings for various tools (pytest, yapf, etc.) used in the project.
+
+# Installation:
+# The Template library can be installed using the command: 'pip install git+https://TOKEN:x-oauth-basic@github.com/ultralytics/template.git@main'
+# For development purposes, you can install the package in editable mode with: 'pip install -e .'
+# This approach allows for real-time code modifications without the need for re-installation.
+
+# Documentation:
+# For comprehensive documentation and usage instructions, visit: https://docs.ultralytics.com
+
+[build-system]
+requires = ["setuptools>=43.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# Project settings -----------------------------------------------------------------------------------------------------
+[project]
+name = "template"  # Required
+version = "0.0.0"  # Required
+description = "Ultralytics Template Python Package"  # Optional
+readme = "README.md"  # Optional
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+keywords = ["Ultralytics", "Template"]  # Optional
+authors = [
+    { name = "Glenn Jocher", email = "glenn.jocher@ultralytics.com" } # Optional
+]
+maintainers = [
+    { name = "Glenn Jocher", email = "glenn.jocher@ultralytics.com" } # Optional
+]
+classifiers = [# Optional, for a list of valid classifiers, see https://pypi.org/classifiers/
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+]
+
+# Required dependencies ------------------------------------------------------------------------------------------------
+dependencies = [# Optional
+    "ultralytics",
+    "numpy",
+]
+
+# Optional dependencies ------------------------------------------------------------------------------------------------
+[project.optional-dependencies] # Optional
+tests = ["pytest"]
+
+[project.urls]  # Optional
+"Bug Reports" = "https://github.com/ultralytics/template/issues"
+"Funding" = "https://ultralytics.com"
+"Source" = "https://github.com/ultralytics/template/"
+
+# [project.scripts]  # Optional
+# sample = "sample:main"  # executes the function `main` from this package when "sample" is called.
+
+# Tools settings -------------------------------------------------------------------------------------------------------
+[tool.setuptools]  # This is configuration specific to the `setuptools` build backend.
+package-data = { "sample" = ["*.yaml"] }
+
+[tool.ruff]
+line-length = 120

template/README.md

@@ -0,0 +1,18 @@
+<br>
+<img src="https://raw.githubusercontent.com/ultralytics/assets/main/logo/Ultralytics_Logotype_Original.svg" width="320">
+
+# Source Code Directory (`/template`)
+
+The root directory of this project serves as the container for the Python source code.
+
+## Structure
+
+- Our project is organized directly at the root level into modules and sub-packages.
+- Each sub-package or module resides in its own dedicated folder or file right at the root.
+- The `pyproject.toml` file, also at the root of our project, defines the packaging configurations.
+
+## Guidelines
+
+- Ensure that code is well-documented and adheres to Ultralytics coding standards.
+- Introduce new modules or packages as necessary, maintaining a logical and clean structure directly at the root level.
+- All code should be rigorously tested and verified for functionality and performance, ensuring high-quality standards are upheld.

template/__init__.py

@@ -0,0 +1 @@
+__version__ == "0.0.0"

template/module1.py

@@ -0,0 +1,3 @@
+def add_numbers(a, b):
+    """Add two numbers."""
+    return a + b

tests/README.md

@@ -0,0 +1,21 @@
+<br>
+<img src="https://raw.githubusercontent.com/ultralytics/assets/main/logo/Ultralytics_Logotype_Original.svg" width="320">
+
+# Tests Directory (`tests/`)
+
+This directory houses the tests for our project, primarily using pytest for testing.
+
+## Overview
+
+- Contains test scripts written in Python.
+- Organized to mirror the structure of the `src/` directory for easy reference.
+- Tests should be comprehensive and cover a wide range of cases.
+
+## Running Tests
+
+To execute the tests:
+
+1. **Install pytest:** Ensure pytest is installed in your environment.
+2. **Run Tests:** Execute `pytest` in the root directory of the project.
+
+Make sure to regularly run tests to maintain the reliability and quality of the project.

tests/test_module1.py

@@ -0,0 +1,8 @@
+from module1 import add_numbers
+
+
+def test_add_numbers():
+    """Test the add_numbers function from module1."""
+    assert add_numbers(2, 3) == 5
+    assert add_numbers(-1, 1) == 0
+    assert add_numbers(-1, -1) == -2