ultralytics/docs

📚 Ultralytics Docs

Welcome to Ultralytics Docs, your comprehensive resource for understanding and utilizing our state-of-the-art machine learning tools and models, including Ultralytics YOLO. These documents are actively maintained and deployed to https://docs.ultralytics.com for easy access.

🛠️ Installation

To install the ultralytics package in developer mode, which allows you to modify the source code directly, ensure you have Git and Python 3.9 or later installed on your system. Then, follow these steps:

1. Clone the ultralytics repository to your local machine using Git:

   git clone https://github.com/ultralytics/ultralytics.git
   

2. Navigate to the cloned repository's root directory:

   cd ultralytics
   

3. Install the package in editable mode (-e) along with its development dependencies ([dev]) using pip:

   pip install -e '.[dev]'
   

   This command installs the ultralytics package such that changes to the source code are immediately reflected in your environment, ideal for development.

🚀 Building and Serving Locally

The mkdocs serve command builds and serves a local version of your MkDocs documentation. This is highly useful during development and testing to preview changes.

mkdocs serve

• Command Breakdown:
  • mkdocs: The main MkDocs command-line interface tool.
  • serve: The subcommand used to build and locally serve your documentation site.
• Note:
  • mkdocs serve includes live reloading, automatically updating the preview in your browser as you save changes to the documentation files.
  • To stop the local server, simply press CTRL+C in your terminal.

🌍 Building and Serving Multi-Language

If your documentation supports multiple languages, follow these steps to build and preview all versions:

1. Stage all new or modified language Markdown (.md) files using Git:

   git add docs/**/*.md -f
   

2. Build all language versions into the /site directory. This script ensures that relevant root-level files are included and clears the previous build:

   # Clear existing /site directory to prevent conflicts
   rm -rf site
   
   # Build the default language site using the primary config file
   mkdocs build -f docs/mkdocs.yml
   
   # Loop through each language-specific config file and build its site
   for file in docs/mkdocs_*.yml; do
     echo "Building MkDocs site with $file"
     mkdocs build -f "$file"
   done
   

3. To preview the complete multi-language site locally, navigate into the build output directory and start a simple Python HTTP server:

   cd site
   python -m http.server
   # Open http://localhost:8000 in your preferred web browser
   

   Access the live preview site at http://localhost:8000.

📤 Deploying Your Documentation Site

To deploy your MkDocs documentation site, choose a hosting provider and configure your deployment method. Common options include GitHub Pages, GitLab Pages, or other static site hosting services.

• Configure deployment settings within your mkdocs.yml file.
• Use the mkdocs deploy command specific to your chosen provider to build and deploy your site.

• GitHub Pages Deployment Example: If deploying to GitHub Pages, you can use the built-in command:

  mkdocs gh-deploy
  

  After deployment, you might need to update the "Custom domain" settings in your repository's settings page if you wish to use a personalized URL.

  

• For detailed instructions on various deployment methods, consult the official MkDocs Deploying your docs guide.

💡 Contribute

We deeply value contributions from the open-source community to enhance Ultralytics projects. Your input helps drive innovation! Please review our Contributing Guide for detailed information on how to get involved. You can also share your feedback and ideas through our Survey. A heartfelt thank you 🙏 to all our contributors for their dedication and support!

We look forward to your contributions!

📜 License

Ultralytics Docs are available under two licensing options to accommodate different usage scenarios:

• AGPL-3.0 License: Ideal for students, researchers, and enthusiasts involved in academic pursuits and open collaboration. See the LICENSE file for full details. This license promotes sharing improvements back with the community.
• Enterprise License: Designed for commercial applications, this license allows seamless integration of Ultralytics software and AI models into commercial products and services. Visit Ultralytics Licensing for more information on obtaining an Enterprise License.

✉️ Contact

For bug reports, feature requests, and other issues related to the documentation, please use GitHub Issues. For discussions, questions, and community support, join the conversation with peers and the Ultralytics team on our Discord server!