Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md #9

Merged
merged 4 commits into from
Oct 14, 2024
Merged

Update README.md #9

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4577c4f
Update README.md
glenn-jocher Oct 14, 2024
0cd06c3
Update README.md
glenn-jocher Oct 14, 2024
d135d8d
Update README.md
glenn-jocher Oct 14, 2024
a28b53c
Update README.md
glenn-jocher Oct 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 29 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,130 +3,80 @@

# 📚 Ultralytics Handbook

The Ultralytics Handbook is your guide to our mission, vision, values, and practices, providing key insights and resources to align with Ultralytics' core principles. This repository is built and maintained directly from the **Handbook repo**, reflecting the latest updates.
Welcome to the **Ultralytics Handbook repository**, the source for all the content that forms the official [Ultralytics Handbook](https://handbook.ultralytics.com). This repository contains Markdown files that outline our **mission, vision, values, and internal practices**, and is designed to provide clarity on how Ultralytics operates. The Handbook is built using **MkDocs Material** and is continuously updated to reflect the latest company guidelines. It is deployed via GitHub Pages to [https://handbook.ultralytics.com](https://handbook.ultralytics.com).

[![pages-build-deployment](https://github.com/ultralytics/handbook/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/ultralytics/handbook/actions/workflows/pages/pages-build-deployment)
[![Check Broken links](https://github.com/ultralytics/handbook/actions/workflows/links.yml/badge.svg)](https://github.com/ultralytics/handbook/actions/workflows/links.yml)
[![Ultralytics Actions](https://github.com/ultralytics/handbook/actions/workflows/format.yml/badge.svg)](https://github.com/ultralytics/handbook/actions/workflows/format.yml)

<a href="https://discord.com/invite/ultralytics"><img alt="Discord" src="https://img.shields.io/discord/1089800235347353640?logo=discord&logoColor=white&label=Discord&color=blue"></a> <a href="https://community.ultralytics.com/"><img alt="Ultralytics Forums" src="https://img.shields.io/discourse/users?server=https%3A%2F%2Fcommunity.ultralytics.com&logo=discourse&label=Forums&color=blue"></a> <a href="https://reddit.com/r/ultralytics"><img alt="Ultralytics Reddit" src="https://img.shields.io/reddit/subreddit-subscribers/ultralytics?style=flat&logo=reddit&logoColor=white&label=Reddit&color=blue"></a>

This Handbook serves as a **living document**—evolving as Ultralytics grows—and is intended to align team members, contributors, and the community with the principles that drive our work. Whether you're new to Ultralytics or a long-standing team member, this Handbook is here to guide you through everything from company philosophy to detailed workflows and processes.

## 🛠️ Installation

[![PyPI - Version](https://img.shields.io/pypi/v/ultralytics?logo=pypi&logoColor=white)](https://pypi.org/project/ultralytics/)
[![Downloads](https://static.pepy.tech/badge/ultralytics)](https://pepy.tech/project/ultralytics)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ultralytics?logo=python&logoColor=gold)](https://pypi.org/project/ultralytics/)

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 cloned repository's root directory:

```bash
cd ultralytics
```

3. Install the package in developer mode using pip (or pip3 for Python 3):
To install MkDocs and all the dependencies required to build and develop the Handbook site, simply run:

```bash
pip install -e '.[dev]'
```
```bash
pip install black mkdocs-material mkdocs-ultralytics-plugin
```

- 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.
This command sets up MkDocs and its required plugins, enabling local development and testing of the Handbook documentation.

## 🚀 Building and Serving Locally

The `mkdocs serve` command builds and serves a local version of your MkDocs documentation, ideal for development and testing:
Use the following command to build and serve a local instance of the Handbook:

```bash
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`.
This will start a local server with live reloading, allowing you to see updates as you modify the content.

## 🌍 Building and Serving Multi-Language
### Key Details:

Supporting multi-language documentation? Follow these steps:
- **`mkdocs`**: The primary command-line interface for MkDocs.
- **`serve`**: Builds the site and serves it locally with live reload.

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

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

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

```bash
# 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:

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

- 🖥️ Access the live site at `http://localhost:8000`.
To stop the server, simply press `CTRL+C`.

## 📤 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.
To deploy the Handbook to GitHub Pages or any other hosting platform:

* ### GitHub Pages Deployment Example:
```bash
mkdocs gh-deploy
```
1. Configure your `mkdocs.yml` with deployment settings.
2. Run the following command to deploy:

- Update the "Custom domain" in your repository's settings for a personalized URL.
```bash
mkdocs gh-deploy
```

![196814117-fc16e711-d2be-4722-9536-b7c6d78fd167](https://user-images.githubusercontent.com/26833433/210150206-9e86dcd7-10af-43e4-9eb2-9518b3799eac.png)
For a custom domain, update the "Custom domain" settings in your GitHub repository to use [handbook.ultralytics.com](https://handbook.ultralytics.com).

- For detailed deployment guidance, consult the [MkDocs documentation](https://www.mkdocs.org/user-guide/deploying-your-docs/).
![Deployment Example](https://user-images.githubusercontent.com/26833433/210150206-9e86dcd7-10af-43e4-9eb2-9518b3799eac.png)

## 💡 Contribute
For further instructions, refer to the [MkDocs deployment guide](https://www.mkdocs.org/user-guide/deploying-your-docs/).

We value community contributions and feedback to continuously improve the Ultralytics Handbook. For guidelines on contributing, please refer to the [Contributing Guide](https://docs.ultralytics.com/help/contributing/).
## 💡 Contributing

<!-- Pictorial representation of our dedicated contributor community -->
We welcome contributions to the Ultralytics Handbook! Whether you're helping improve documentation or proposing new ideas, your input is valuable. For more details on how to contribute, please see our [Contributing Guide](https://docs.ultralytics.com/help/contributing/).

![Ultralytics open-source contributors](https://raw.githubusercontent.com/ultralytics/assets/main/im/image-contributors.png)

## 📜 License

The Ultralytics Handbook is licensed under the following options:
The Ultralytics Handbook is available under the following licenses:

- **AGPL-3.0 License**: Suitable for academic and collaborative work. See the [LICENSE](https://github.com/ultralytics/handbook/blob/main/LICENSE) file for details.
- **Enterprise License**: Ideal for commercial use, integrating Ultralytics' solutions into proprietary products. Visit [Ultralytics Licensing](https://www.ultralytics.com/license) for more details.
- **AGPL-3.0 License**: Designed for academic and open-source projects. Refer to the [LICENSE](https://github.com/ultralytics/handbook/blob/main/LICENSE) file for specifics.
- **Enterprise License**: Suitable for commercial applications of Ultralytics technologies. Visit [Ultralytics Licensing](https://www.ultralytics.com/license) for more information.

## ✉️ Contact

For bug reports or feature requests, please use [GitHub Issues](https://github.com/ultralytics/handbook/issues). You can also engage with the Ultralytics team and community on [Discord](https://discord.com/invite/ultralytics).
For any issues, bug reports, or feature requests, please use [GitHub Issues](https://github.com/ultralytics/handbook/issues). You can also join the conversation on [Discord](https://discord.com/invite/ultralytics) to engage with the Ultralytics community and team.

<br>
<div align="center">
Expand Down