Ultralytics Handbook

https://handbook.ultralytics.com
Admin
The Ultralytics Handbook is a comprehensive guide covering company mission, values, policies,...
Tokens:42,841
Snippets:578
Trust Score:10
Update:9 months ago
Show doc for...
Tokens:
Raw
### Clone and Install Ultralytics Repository

Source: https://handbook.ultralytics.com/people/onboarding

This snippet demonstrates how to clone the Ultralytics GitHub repository, navigate into the directory, install the project dependencies in editable mode, and verify the installation using the 'yolo checks' command. It's essential for setting up the development environment for engineering roles.

```shell
# Clone repositories
git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics

# Install dependencies
pip install -e .

# Verify installation
yolo checks

```

--------------------------------

### Python Package Installation for Docs

Source: https://handbook.ultralytics.com/workflows/documentation

Command to install development dependencies for documentation, including necessary packages for local building and serving. This is typically run in a virtual environment.

```bash
pip install -e ".[docs]"

```

--------------------------------

### Runnable Python Code Example for YOLO Training

Source: https://handbook.ultralytics.com/workflows/documentation

Provides a runnable Python code snippet demonstrating how to load a pre-trained YOLO model and initiate a training process with specified data and epochs. This example is intended to be copy-paste functional.

```python
from ultralytics import YOLO

# Load pretrained model
model = YOLO("yolo11n.pt")

# Train on custom data
results = model.train(data="coco8.yaml", epochs=3)

```

--------------------------------

### Install Development Dependencies - Python

Source: https://handbook.ultralytics.com/workflows/ci-testing

Installs the necessary development dependencies for the project, including testing and linting tools, using pip.

```python
pip install -e ".[dev]"
```

--------------------------------

### Update MkDocs Navigation

Source: https://handbook.ultralytics.com/workflows/documentation

Example of modifying the `mkdocs.yml` file to include a new page in the site's navigation structure. It shows how to add a new guide under the 'Guides' section.

```yaml
nav:
    - Home: 
    - Guides:
          - New Guide: guides/new-guide/

```

--------------------------------

### MkDocs Configuration Example

Source: https://handbook.ultralytics.com/workflows/documentation

A snippet of the MkDocs configuration file (`mkdocs.yml`) showing essential settings like site name, theme, and enabled plugins. It highlights the use of the 'material' theme and the 'search' plugin.

```yaml
site_name: Ultralytics Docs
theme:
    name: material
    palette:
        - scheme: slate
plugins:
    - search
    - ultralytics

```

--------------------------------

### Parallel Testing Setup and Execution - Pytest

Source: https://handbook.ultralytics.com/workflows/ci-testing

Enables running pytest tests in parallel across multiple CPU cores to speed up execution. Requires the 'pytest-xdist' plugin.

```python
# Install pytest-xdist
pip install pytest-xdist
```

```python
# Run tests in parallel
pytest -n auto
```

--------------------------------

### Python Function Docstring for API Reference

Source: https://handbook.ultralytics.com/workflows/documentation

An example of a Python function docstring formatted to generate API documentation. It includes a brief description, arguments with types, return value description, and a runnable code example.

```python
def train(self, data, epochs=100, batch=16):
    """
    Train the model on a dataset.

    Args:
        data (str): Path to data YAML file
        epochs (int): Number of training epochs
        batch (int): Batch size

    Returns:
        (Results): Training results

    Examples:
        ```python
        model = YOLO("yolo11n.pt")
        results = model.train(data="coco8.yaml", epochs=100)
        ```
    """


```

--------------------------------

### Docstring Formatting Automation - Python

Source: https://handbook.ultralytics.com/workflows/ci-testing

Installs the 'ultralytics-actions' package and provides a command to automatically format Python docstrings within the current directory.

```python
pip install ultralytics-actions
```

```python
# Auto-fix
ultralytics-actions-format-python-docstrings .
```

--------------------------------

### Google-Style Docstring - Multiple Returns Format (Python)

Source: https://handbook.ultralytics.com/workflows/development

Provides an example of the correct formatting for documenting multiple return values in Python Google-style docstrings, avoiding tuple descriptions.

```python
Returns:
    (np.ndarray): Predicted masks with shape HxWxN.
    (list): Confidence scores for each instance.

```

--------------------------------

### Markdown Frontmatter and Basic Structure

Source: https://handbook.ultralytics.com/workflows/documentation

Defines the metadata for a documentation page, including SEO descriptions and keywords, followed by the main title and an introductory paragraph. It also demonstrates basic sectioning and including Python code examples.

```markdown
---
description: Brief page description for SEO
keywords: relevant, keywords, for, search
---

# Page Title

Brief introduction explaining what this page covers.

## Section Heading

Content with examples:

```python
from ultralytics import YOLO

# Load pretrained model
model = YOLO("yolo11n.pt")
results = model("image.jpg")
```

### Key points:

- Use bullet points for lists
- Keep paragraphs short
- Include links to related pages

```

--------------------------------

### MkDocs Local Development Server

Source: https://handbook.ultralytics.com/workflows/documentation

Command to build and serve the documentation locally using MkDocs. This allows developers to preview changes before committing them.

```bash
mkdocs serve

```

--------------------------------

### Create New Markdown Documentation File

Source: https://handbook.ultralytics.com/workflows/documentation

Shell command to create a new, empty Markdown file in the specified directory for documentation. This is the first step in adding a new page.

```bash
touch docs/en/guides/new-guide/

```
Tokens:
Raw