From fe75a9ce6773dacdea1ef9d886384d727b3232d6 Mon Sep 17 00:00:00 2001 From: Ayush Chaurasia Date: Mon, 5 Dec 2022 06:04:57 +0530 Subject: [PATCH] docs setup (#61) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .pre-commit-config.yaml | 3 +- CONTRIBUTING.md | 31 +++++++++++++ docs/README.md | 7 +++ docs/assets/logo.png | Bin 0 -> 6354 bytes docs/cli.md | 72 +++++++++++++++++++++++++++++ docs/conf.md | 0 docs/index.md | 3 ++ docs/quickstart.md | 45 +++++++++++++++++++ docs/reference/ref.md | 0 docs/sdk.md | 11 +++++ docs/tasks/classification.md | 0 docs/tasks/detection.md | 0 docs/tasks/segmentation.md | 0 docs/trainer.md | 0 mkdocs.yml | 85 +++++++++++++++++++++++++++++++++++ setup.py | 4 +- 16 files changed, 258 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/README.md create mode 100644 docs/assets/logo.png create mode 100644 docs/cli.md create mode 100644 docs/conf.md create mode 100644 docs/index.md create mode 100644 docs/quickstart.md create mode 100644 docs/reference/ref.md create mode 100644 docs/sdk.md create mode 100644 docs/tasks/classification.md create mode 100644 docs/tasks/detection.md create mode 100644 docs/tasks/segmentation.md create mode 100644 docs/trainer.md create mode 100644 mkdocs.yml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ba80055..661d1f8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,6 +4,7 @@ default_language_version: python: python3.8 +exclude: 'docs/' # Define bot property if installed via https://github.com/marketplace/pre-commit-ci ci: autofix_prs: true @@ -50,7 +51,7 @@ repos: additional_dependencies: - mdformat-gfm - mdformat-black - exclude: "README.md|README_cn.md" + exclude: "README.md|README_cn.md| CONTRIBUTING.md" - repo: https://github.com/asottile/yesqa rev: v1.4.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9c11216 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +## Contributing to Ultralytics: The YOLO framework + +We love your input! We want to make contributing to YOLOv5 as easy and transparent as possible, whether it's: + +Reporting a bug +Discussing the current state of the code +Submitting a fix +Proposing a new feature +Becoming a maintainer + +Here are some things to keep in mind when making PRs: + +### Docstrings + +Not all functions or classes require docstrings but when they do, we follow [google-stlye docstrings format](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings). Here is an example: + +``` +''' + What the function does - performs nms on given detection predictions + + Args: + arg1: The description of the 1st argument + arg2: The description of the 2nd argument + + Returns: + What the function returns. Empty if nothing is returned + + Raises: + Exception Class: When and why this exception can be raised by the function. +''' +``` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2236b87 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,7 @@ +## To serve docs +* Install ultralytics repo in Dev mode: +``` +cd ultralytics +pip install -e '.[dev]' +``` +* Run `mkdocs serve` diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..fb41ad61ed57d0316220fc61f7212be21b87d7c4 GIT binary patch literal 6354 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 O0yuAV$&zZ0A^aZ=y4)xL literal 0 HcmV?d00001 diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..8b8f41b --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,72 @@ +## CLI Basics +If you want to train, validate or run inference on models and don't need to make any modifications to the code, using YOLO command line interface is the easiest way to get started. + +!!! tip "Syntax" + ```bash + yolo task=detect mode=train model=s.yaml epochs=1 ... + ... ... ... + segment infer s-cls.pt + classify val s-seg.pt + ``` + +The experiment arguments can be overridden directly by pass `arg=val` covered in the next section. You can run any supported task by setting `task` and `mode` in cli. +=== "Training" + + | | `task` | snippet | + | ----------- | ------------- | ----------------------------------------------------------- | + | Detection | `detect` | 
yolo task=detect mode=train
| + | Instance Segment | `segment` | 
yolo task=segment mode=train
| + | Classification | `classify` | 
yolo task=classify mode=train
| + +=== "Inference" + + | | `task` | snippet | + | ----------- | ------------- | ------------------------------------------------------------ | + | Detection | `detect` | 
yolo task=detect mode=infer
| + | Instance Segment | `segment` | 
yolo task=segment mode=infer
| + | Classification | `classify` | 
yolo task=classify mode=infer
| + +=== "Validation" + + | | `task` | snippet | + | ----------- | ------------- | ------------------------------------------------------------- | + | Detection | `detect` | 
yolo task=detect mode=val
| + | Instance Segment | `segment` | 
yolo task=segment mode=val
| + | Classification | `classify` | 
yolo task=classify mode=val
| + +!!! note "" + Note: The arguments don't require `'--'` prefix. These are reserved for special commands covered later +--- +## Overriding default config arguments +All global default arguments can be overriden by simply passing them as arguments in the cli. +!!! tip "" + === "Syntax" + ```yolo task= ... mode= ... {++ arg=val ++}``` + + === "Example" + Perform detection training for `10 epochs` with `learning_rate` of `0.01` + ``` + yolo task=detect mode=train {++ epochs=10 lr0=0.01 ++} + + ``` +--- +## Overriding default config file +You can override config file entirely by passing a new file. You can create a copy of default config file in your current working dir as follows: +```bash +yolo task=init +``` +You can then use special `--cfg name.yaml` command to pass the new config file +```bash +yolo task=detect mode=train {++ --cfg default.yaml ++} +``` + +??? example + === "Command" + ``` + yolo task=init + yolo task=detect mode=train --cfg default.yaml + ``` + === "Result" + TODO: add terminal output + + diff --git a/docs/conf.md b/docs/conf.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..208b23c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +# Welcome to Ultralytics YOLO + +TODO diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..3af3dbf --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,45 @@ +## Installation +!!! note "Latest Stable Release" + ``` + pip install ultralytics + ``` +??? tip "Development and Contributing" + ``` + git clone https://github.com/ultralytics/ultralytics + cd ultralytics + pip install -e '.[dev]' + ``` + See contributing section to know more about contributing to the project + + +## CLI +The command line YOLO interface let's you simply train, validate or infer models on various tasks and versions. +CLI requires no customization or code. You can simply run all tasks from the terminal +!!! tip + === "Syntax" + ```bash + yolo task=detect mode=train model=s.yaml epochs=1 ... + ... ... ... + segment infer s-cls.pt + classify val s-seg.pt + ``` + + === "Example" + ```bash + yolo task=detect mode=val model=s.yaml + ``` + TODO: add terminal screen/gif +[CLI Guide](#){ .md-button .md-button--primary} + +## Python API +Ultralytics YOLO comes with pythonic Model and Trainer interface. +!!! tip + ```python + import ultralytics + from ultralytics import YOLO + model = YOLO() + model.new("s-seg.yaml") # automatically detects task type + model.load("s-seg.pt") # load checkpoint + model.train(data="coco128-segments", epochs=1, lr0=0.01, ...) + ``` +[API Guide](#){ .md-button .md-button--primary} \ No newline at end of file diff --git a/docs/reference/ref.md b/docs/reference/ref.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/sdk.md b/docs/sdk.md new file mode 100644 index 0000000..cbe361b --- /dev/null +++ b/docs/sdk.md @@ -0,0 +1,11 @@ +# Python SDK + +We provide 2 pythonic interfaces for YOLO models: + + Model Interface - To simply build, load, train or run inference on a model in a python application + + Trainer Interface - To customize trainier elements depending on the task. Suitable for R&D ideas like architecutres. + +______________________________________________________________________ + +### Model Interface diff --git a/docs/tasks/classification.md b/docs/tasks/classification.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/tasks/detection.md b/docs/tasks/detection.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/tasks/segmentation.md b/docs/tasks/segmentation.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/trainer.md b/docs/trainer.md new file mode 100644 index 0000000..e69de29 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..04240ff --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,85 @@ +site_name: Ultralytics YOLO Docs +repo_url: https://github.com/ultralytics/yolov5 +repo_name: Ultralytics + +theme: + name: "material" + logo: assets/logo.png + icon: + repo: fontawesome/brands/github + admonition: + note: octicons/tag-16 + abstract: octicons/checklist-16 + info: octicons/info-16 + tip: octicons/squirrel-16 + success: octicons/check-16 + question: octicons/question-16 + warning: octicons/alert-16 + failure: octicons/x-circle-16 + danger: octicons/zap-16 + bug: octicons/bug-16 + example: octicons/beaker-16 + quote: octicons/quote-16 + + palette: + # Palette toggle for light mode + - scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - content.code.annotate + - content.tooltips + - search.highlight + - search.share + - search.suggest + - toc.follow + +markdown_extensions: + # Div text decorators + - admonition + - pymdownx.details + - pymdownx.superfences + - tables + + # Syntax highlight + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + + # button + - attr_list + + # content tabs + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + + # highlight + - pymdownx.critic + - pymdownx.caret + - pymdownx.keys + - pymdownx.mark + - pymdownx.tilde +plugins: + - mkdocstrings + +# primary navigation +nav: + - Quickstart: quickstart.md + - CLI: cli.md + - Python SDK: sdk.md + - Trainer: trainer.md + - Configuration: conf.md + - Tasks: + - Detection: tasks/detection.md + - Segmentation: tasks/segmentation.md + - Classification: tasks/classification.md + - Reference: reference/ref.md \ No newline at end of file diff --git a/setup.py b/setup.py index cd1c0db..6b2c302 100644 --- a/setup.py +++ b/setup.py @@ -35,8 +35,8 @@ setup( include_package_data=True, install_requires=REQUIREMENTS, extras_require={ - 'dev': ['check-manifest'], - 'test': ['pytest', 'pytest-cov', 'coverage'],}, + 'dev': + ['check-manifest', 'pytest', 'pytest-cov', 'coverage', 'mkdocs', 'mkdocstrings[python]', 'mkdocs-material'],}, classifiers=[ "Intended Audience :: Developers", "Intended Audience :: Science/Research", "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "Programming Language :: Python :: 3",