From 5c1277113b19e45292c01e5a47aa2bdb6ebc98d0 Mon Sep 17 00:00:00 2001 From: Glenn Jocher Date: Wed, 13 Mar 2024 16:17:57 +0100 Subject: [PATCH] Update Docs README (#8919) --- docs/README.md | 160 +++++++++++++++++++------------ docs/en/index.md | 2 +- docs/en/integrations/openvino.md | 2 +- 3 files changed, 100 insertions(+), 64 deletions(-) diff --git a/docs/README.md b/docs/README.md index b41e391818..954e130cd0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,104 +1,140 @@ -# Ultralytics Docs +
+ -Ultralytics Docs are deployed to [https://docs.ultralytics.com](https://docs.ultralytics.com). +# 📚 Ultralytics Docs -[![pages-build-deployment](https://github.com/ultralytics/docs/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/pages/pages-build-deployment) [![Check Broken links](https://github.com/ultralytics/docs/actions/workflows/links.yml/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/links.yml) +Ultralytics Docs are the gateway to understanding and utilizing our cutting-edge machine learning tools. These documents are deployed to [https://docs.ultralytics.com](https://docs.ultralytics.com) for your convenience. -## Install Ultralytics package +[![pages-build-deployment](https://github.com/ultralytics/docs/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/pages/pages-build-deployment) [![Check Broken links](https://github.com/ultralytics/docs/actions/workflows/links.yml/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/links.yml) [![Check Domains](https://github.com/ultralytics/docs/actions/workflows/check_domains.yml/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/check_domains.yml) [![Ultralytics Actions](https://github.com/ultralytics/docs/actions/workflows/format.yml/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/format.yml) Discord + +## 🛠️ Installation [![PyPI version](https://badge.fury.io/py/ultralytics.svg)](https://badge.fury.io/py/ultralytics) [![Downloads](https://static.pepy.tech/badge/ultralytics)](https://pepy.tech/project/ultralytics) -To install the ultralytics package in developer mode, you will need to have Git and Python 3 installed on your system. Then, follow these steps: +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: - ```bash - git clone https://github.com/ultralytics/ultralytics.git - ``` - -2. Navigate to the root directory of the repository: + ```bash + git clone https://github.com/ultralytics/ultralytics.git + ``` - ```bash - cd ultralytics - ``` +2. Navigate to the cloned repository's root directory: -3. Install the package in developer mode using pip: + ```bash + cd ultralytics + ``` - ```bash - pip install -e '.[dev]' - ``` +3. Install the package in developer mode using pip (or pip3 for Python 3): -This will install the ultralytics package and its dependencies in developer mode, allowing you to make changes to the package code and have them reflected immediately in your Python environment. + ```bash + pip install -e '.[dev]' + ``` -Note that you may need to use the pip3 command instead of pip if you have multiple versions of Python installed on your system. +- 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 +## 🚀 Building and Serving Locally -The `mkdocs serve` command is used to build and serve a local version of the MkDocs documentation site. It is typically used during the development and testing phase of a documentation project. +The `mkdocs serve` command builds and serves a local version of your MkDocs documentation, ideal for development and testing: ```bash mkdocs serve ``` -Here is a breakdown of what this command does: +- #### Command Breakdown: -- `mkdocs`: This is the command-line interface (CLI) for the MkDocs static site generator. It is used to build and serve MkDocs sites. -- `serve`: This is a subcommand of the `mkdocs` CLI that tells it to build and serve the documentation site locally. -- `-a`: This flag specifies the hostname and port number to bind the server to. The default value is `localhost:8000`. -- `-t`: This flag specifies the theme to use for the documentation site. The default value is `mkdocs`. -- `-s`: This flag tells the `serve` command to serve the site in silent mode, which means it will not display any log messages or progress updates. When you run the `mkdocs serve` command, it will build the documentation site using the files in the `docs/` directory and serve it at the specified hostname and port number. You can then view the site by going to the URL in your web browser. -- `-f`: Flag to specify the filepath to the `mkdocs.yml` file to use for the documentation site; may be useful when file is not located in the current working directory. -- `--dirtyreload`: Use this flag if/when locally served site rebuilds are expensive and require a long time to rebuild. Including this will only rebuild files that have changed and some elements may not reflect updates. + - `mkdocs` is the main MkDocs command-line interface. + - `serve` is the subcommand to build and locally serve your documentation. -While the site is being served, you can make changes to the documentation files and see them reflected in the live site immediately. This is useful for testing and debugging your documentation before deploying it to a live server. +- 🧐 Note: -To stop the serve command and terminate the local server, you can use the `CTRL+C` keyboard shortcut. + - 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 +## 🌍 Building and Serving Multi-Language -For multi-language MkDocs sites use the following additional steps: +Supporting multi-language documentation? Follow these steps: -1. Add all new language `*.md` files to git commit: `git add docs/**/*.md -f` -2. Build all languages to the `/site` directory. Verify that the top-level `/site` directory contains `CNAME`, `robots.txt` and `sitemap.xml` files, if applicable. +1. Stage all new language \*.md files with Git: - ```bash - # Remove existing /site directory - rm -rf site + ```bash + git add docs/**/*.md -f + ``` - # Loop through all YAML files in the docs directory - mkdocs build -f docs/mkdocs.yml - for file in docs/mkdocs_*.yml; do - echo "Building MkDocs site with configuration file: $file" - mkdocs build -f "$file" - done - ``` +2. Build all languages to the `/site` folder, ensuring relevant root-level files are present: -3. Preview in web browser with: + ```bash + # Clear existing /site directory + rm -rf site - ```bash - cd site - python -m http.server - open http://localhost:8000 # on macOS - ``` + # 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 + ``` -Note the above steps are combined into the Ultralytics [build_docs.py](https://github.com/ultralytics/ultralytics/blob/main/docs/build_docs.py) script. +3. To preview your site, initiate a simple HTTP server: -## Deploying Your Documentation Site + ```bash + cd site + python -m http.server + # Open in your preferred browser + ``` -To deploy your MkDocs documentation site, you will need to choose a hosting provider and a deployment method. Some popular options include GitHub Pages, GitLab Pages, and Amazon S3. +- 🖥️ Access the live site at `http://localhost:8000`. -Before you can deploy your site, you will need to configure your `mkdocs.yml` file to specify the remote host and any other necessary deployment settings. +## 📤 Deploying Your Documentation Site -Once you have configured your `mkdocs.yml` file, you can use the `mkdocs deploy` command to build and deploy your site. This command will build the documentation site using the files in the `docs/` directory and the specified configuration file and theme, and then deploy the site to the specified remote host. +Choose a hosting provider and deployment method for your MkDocs documentation: -For example, to deploy your site to GitHub Pages using the gh-deploy plugin, you can use the following command: +- Configure `mkdocs.yml` with deployment settings. +- Use `mkdocs deploy` to build and deploy your site. -```bash -mkdocs gh-deploy -``` +* ### GitHub Pages Deployment Example: + ```bash + mkdocs gh-deploy + ``` -If you are using GitHub Pages, you can set a custom domain for your documentation site by going to the "Settings" page for your repository and updating the "Custom domain" field in the "GitHub Pages" section. +- Update the "Custom domain" in your repository's settings for a personalized URL. ![196814117-fc16e711-d2be-4722-9536-b7c6d78fd167](https://user-images.githubusercontent.com/26833433/210150206-9e86dcd7-10af-43e4-9eb2-9518b3799eac.png) -For more information on deploying your MkDocs documentation site, see the [MkDocs documentation](https://www.mkdocs.org/user-guide/deploying-your-docs/). +- For detailed deployment guidance, consult the [MkDocs documentation](https://www.mkdocs.org/user-guide/deploying-your-docs/). + +## 💡 Contribute + +We cherish the community's input as it drives Ultralytics open-source initiatives. Dive into the [Contributing Guide](https://docs.ultralytics.com/help/contributing) and share your thoughts via our [Survey](https://ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey). A heartfelt thank you 🙏 to each contributor! + + + +![Ultralytics open-source contributors](https://github.com/ultralytics/assets/raw/main/im/image-contributors.png) + +## 📜 License + +Ultralytics presents two licensing options: + +- **AGPL-3.0 License**: Perfect for academia and open collaboration. Details are in the [LICENSE](https://github.com/ultralytics/ultralytics/blob/main/LICENSE) file. +- **Enterprise License**: Tailored for commercial usage, offering a seamless blend of Ultralytics technology in your products. Learn more at [Ultralytics Licensing](https://ultralytics.com/license). + +## ✉️ Contact + +For bug reports and feature requests, navigate to [GitHub Issues](https://github.com/ultralytics/docs/issues). Engage with peers and the Ultralytics team on [Discord](https://ultralytics.com/discord) for enriching conversations! + +
+
+ Ultralytics GitHub + space + Ultralytics LinkedIn + space + Ultralytics Twitter + space + Ultralytics YouTube + space + Ultralytics TikTok + space + Ultralytics Instagram + space + Ultralytics Discord +
diff --git a/docs/en/index.md b/docs/en/index.md index 1c95078fa9..484f51b6c6 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -69,7 +69,7 @@ Explore the YOLOv8 Docs, a comprehensive resource designed to help you understan - [YOLOv6](https://github.com/meituan/YOLOv6) was open-sourced by [Meituan](https://about.meituan.com/) in 2022 and is in use in many of the company's autonomous delivery robots. - [YOLOv7](https://github.com/WongKinYiu/yolov7) added additional tasks such as pose estimation on the COCO keypoints dataset. - [YOLOv8](https://github.com/ultralytics/ultralytics) is the latest version of YOLO by Ultralytics. As a cutting-edge, state-of-the-art (SOTA) model, YOLOv8 builds on the success of previous versions, introducing new features and improvements for enhanced performance, flexibility, and efficiency. YOLOv8 supports a full range of vision AI tasks, including [detection](tasks/detect.md), [segmentation](tasks/segment.md), [pose estimation](tasks/pose.md), [tracking](modes/track.md), and [classification](tasks/classify.md). This versatility allows users to leverage YOLOv8's capabilities across diverse applications and domains. -- [YOLOv9] (https://github.com/WongKinYiu/yolov9) Introduces innovative methods like Programmable Gradient Information (PGI) and the Generalized Efficient Layer Aggregation Network (GELAN). +- [YOLOv9](models/yolov9.md) Introduces innovative methods like Programmable Gradient Information (PGI) and the Generalized Efficient Layer Aggregation Network (GELAN). ## YOLO Licenses: How is Ultralytics YOLO licensed? diff --git a/docs/en/integrations/openvino.md b/docs/en/integrations/openvino.md index 657a4a5365..4234d78d57 100644 --- a/docs/en/integrations/openvino.md +++ b/docs/en/integrations/openvino.md @@ -83,7 +83,7 @@ You can use these files to run inference with the OpenVINO Inference Engine. ## Using OpenVINO Export in Deployment -Once you have the OpenVINO files, you can use the OpenVINO Runtime to run the model. The Runtime provides a unified API to inference across all supported Intel hardware. It also provides advanced capabilities like load balancing across Intel hardware and asynchronous execution. For more information on running the inference, refer to the [Inference with OpenVINO Runtime Guide](https://docs.openvino.ai/nightly/openvino_docs_OV_UG_OV_Runtime_User_Guide.html). +Once you have the OpenVINO files, you can use the OpenVINO Runtime to run the model. The Runtime provides a unified API to inference across all supported Intel hardware. It also provides advanced capabilities like load balancing across Intel hardware and asynchronous execution. For more information on running the inference, refer to the [Inference with OpenVINO Runtime Guide](https://docs.openvino.ai/2024/openvino-workflow/running-inference.html). Remember, you'll need the XML and BIN files as well as any application-specific settings like input size, scale factor for normalization, etc., to correctly set up and use the model with the Runtime.