docs setup (#61)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.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

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.
+'''
+```

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`

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`       | <pre><code>yolo task=detect mode=train       </code></pre>  |
+    |  Instance Segment  |  `segment`      | <pre><code>yolo task=segment mode=train      </code></pre>  |
+    |  Classification    |  `classify`     | <pre><code>yolo task=classify mode=train    </code></pre>   |
+
+=== "Inference"
+
+    |                    | `task`          | snippet                                                      |
+    | -----------        | -------------   | ------------------------------------------------------------ |
+    |  Detection         |  `detect`       | <pre><code>yolo task=detect mode=infer       </code></pre>   |
+    |  Instance Segment  |  `segment`      | <pre><code>yolo task=segment mode=infer     </code></pre>    |
+    |  Classification    |  `classify`     | <pre><code>yolo task=classify mode=infer    </code></pre>    |
+
+=== "Validation"
+
+    |                    | `task`          | snippet                                                       |
+    | -----------        | -------------   | ------------------------------------------------------------- |
+    |  Detection         |  `detect`       | <pre><code>yolo task=detect mode=val        </code></pre>     |
+    |  Instance Segment  |  `segment`      | <pre><code>yolo task=segment mode=val       </code></pre>     |
+    |  Classification    |  `classify`     | <pre><code>yolo task=classify mode=val      </code></pre>     |
+
+!!! note ""
+    <b>Note:</b> 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
+
+

docs/index.md

@@ -0,0 +1,3 @@
+# Welcome to Ultralytics YOLO
+
+TODO

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}

docs/sdk.md

@@ -0,0 +1,11 @@
+# Python SDK
+
+We provide 2 pythonic interfaces for YOLO models:
+
+<b> Model Interface </b> - To simply build, load, train or run inference on a model in a python application
+
+<b> Trainer Interface </b> - To customize trainier elements depending on the task. Suitable for R&D ideas like architecutres.
+
+______________________________________________________________________
+
+### Model Interface

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

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",