ultralytics/docs/README.md

📚 Ultralytics Docs

Ultralytics Docs are the gateway to understanding and utilizing our cutting-edge machine learning tools. These documents are deployed to https://docs.ultralytics.com for your convenience.

🛠️ Installation

To install the ultralytics package in developer mode, ensure you have Git and Python 3 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 developer mode using pip (or pip3 for Python 3):

   pip install -e '.[dev]'
   

• This command installs the ultralytics package along with all development dependencies, allowing you to modify the package code and have the changes immediately reflected in your Python environment.

🚀 Building and Serving Locally

The mkdocs serve command builds and serves a local version of your MkDocs documentation, ideal for development and testing:

mkdocs serve

• Command Breakdown:

  • mkdocs is the main MkDocs command-line interface.
  • serve is the subcommand to build and locally serve your documentation.

• 🧐 Note:

  • Grasp changes to the docs in real-time as mkdocs serve supports live reloading.
  • To stop the local server, press CTRL+C.

🌍 Building and Serving Multi-Language

Supporting multi-language documentation? Follow these steps:

1. Stage all new language *.md files with Git:

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

2. Build all languages to the /site folder, ensuring relevant root-level files are present:

   # Clear existing /site directory
   rm -rf site
   
   # Loop through each language config file and build
   mkdocs build -f docs/mkdocs.yml
   for file in docs/mkdocs_*.yml; do
     echo "Building MkDocs site with $file"
     mkdocs build -f "$file"
   done
   

3. To preview your site, initiate a simple HTTP server:

   cd site
   python -m http.server
   # Open in your preferred browser
   

• 🖥️ Access the live site at http://localhost:8000.

📤 Deploying Your Documentation Site

Choose a hosting provider and deployment method for your MkDocs documentation:

• Configure mkdocs.yml with deployment settings.
• Use mkdocs deploy to build and deploy your site.

• GitHub Pages Deployment Example:

  mkdocs gh-deploy
  

• Update the "Custom domain" in your repository's settings for a personalized URL.

• For detailed deployment guidance, consult the MkDocs documentation.

💡 Contribute

We cherish the community's input as it drives Ultralytics open-source initiatives. Dive into the Contributing Guide and share your thoughts via our Survey. A heartfelt thank you 🙏 to each contributor!

📜 License

Ultralytics Docs presents two licensing options:

• AGPL-3.0 License: Perfect for academia and open collaboration. Details are in the LICENSE file.
• Enterprise License: Tailored for commercial usage, offering a seamless blend of Ultralytics technology in your products. Learn more at Ultralytics Licensing.

✉️ Contact

For Ultralytics bug reports and feature requests please visit GitHub Issues. Become a member of the Ultralytics Discord, Reddit, or Forums for asking questions, sharing projects, learning discussions, or for help with all things Ultralytics!