build webpage of documentation (#352)

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+   - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+   version: "3.7"
+   install:
+   - requirements: docs/requirements-doc.txt
+   - requirements: requirements.txt

demo/MegEngine/cpp/README.md

@@ -12,85 +12,108 @@ Cpp file compile of YOLOX object detection base on [MegEngine](https://github.co
 
 ### Step2: build MegEngine
 
- * git clone https://github.com/MegEngine/MegEngine.git
- * then init third_party
-    * then export megengine_root="path of MegEngine"
-    * cd $megengine_root && ./third_party/prepare.sh && ./third_party/install-mkl.sh
- * build example:
-    * build host without cuda:   ./scripts/cmake-build/host_build.sh
-    * build host with cuda      :   ./scripts/cmake-build/host_build.sh -c
-    * cross build for android aarch64: ./scripts/cmake-build/cross_build_android_arm_inference.sh
-    * cross build for android aarch64(with V8.2+fp16): ./scripts/cmake-build/cross_build_android_arm_inference.sh -f
-* after build MegEngine, you need export the `MGE_INSTALL_PATH`
-  * host without cuda: export MGE_INSTALL_PATH=${megengine_root}/build_dir/host/MGE_WITH_CUDA_OFF/MGE_INFERENCE_ONLY_ON/Release/install
-  * host with cuda: export MGE_INSTALL_PATH=${megengine_root}/build_dir/host/MGE_WITH_CUDA_ON/MGE_INFERENCE_ONLY_ON/Release/install
-  * cross build for android aarch64: export MGE_INSTALL_PATH=${megengine_root}/build_dir/android/arm64-v8a/Release/install
+```shell
+git clone https://github.com/MegEngine/MegEngine.git
+
+# then init third_party
+ 
+export megengine_root="path of MegEngine"
+cd $megengine_root && ./third_party/prepare.sh && ./third_party/install-mkl.sh
+
+# build example:
+# build host without cuda:   
+./scripts/cmake-build/host_build.sh
+# or build host with cuda:
+./scripts/cmake-build/host_build.sh -c
+# or cross build for android aarch64: 
+./scripts/cmake-build/cross_build_android_arm_inference.sh
+# or cross build for android aarch64(with V8.2+fp16): 
+./scripts/cmake-build/cross_build_android_arm_inference.sh -f
+
+# after build MegEngine, you need export the `MGE_INSTALL_PATH`
+# host without cuda: 
+export MGE_INSTALL_PATH=${megengine_root}/build_dir/host/MGE_WITH_CUDA_OFF/MGE_INFERENCE_ONLY_ON/Release/install
+# or host with cuda: 
+export MGE_INSTALL_PATH=${megengine_root}/build_dir/host/MGE_WITH_CUDA_ON/MGE_INFERENCE_ONLY_ON/Release/install
+# or cross build for android aarch64: 
+export MGE_INSTALL_PATH=${megengine_root}/build_dir/android/arm64-v8a/Release/install
+```
 * you can refs [build tutorial of MegEngine](https://github.com/MegEngine/MegEngine/blob/master/scripts/cmake-build/BUILD_README.md) to build other platform, eg, windows/macos/ etc!
 
 ### Step3: build OpenCV
-* git clone https://github.com/opencv/opencv.git
-
-* git checkout 3.4.15 (we test at 3.4.15, if test other version, may need modify some build)
-
-* patch diff for android:
-
-  * ```
-    diff --git a/CMakeLists.txt b/CMakeLists.txt
-    index f6a2da5310..10354312c9 100644
-    --- a/CMakeLists.txt
-    +++ b/CMakeLists.txt
-    @@ -643,7 +643,7 @@ if(UNIX)
-       if(NOT APPLE)
-         CHECK_INCLUDE_FILE(pthread.h HAVE_PTHREAD)
-         if(ANDROID)
-    -      set(OPENCV_LINKER_LIBS ${OPENCV_LINKER_LIBS} dl m log)
-    +      set(OPENCV_LINKER_LIBS ${OPENCV_LINKER_LIBS} dl m log z)
-         elseif(CMAKE_SYSTEM_NAME MATCHES "FreeBSD|NetBSD|DragonFly|OpenBSD|Haiku")
-           set(OPENCV_LINKER_LIBS ${OPENCV_LINKER_LIBS} m pthread)
-         elseif(EMSCRIPTEN)
+
+```shell
+git clone https://github.com/opencv/opencv.git
+
+git checkout 3.4.15 (we test at 3.4.15, if test other version, may need modify some build)
+```
+
+- patch diff for android:
+
+```
+# ```
+#     diff --git a/CMakeLists.txt b/CMakeLists.txt
+#     index f6a2da5310..10354312c9 100644
+#     --- a/CMakeLists.txt
+#     +++ b/CMakeLists.txt
+#     @@ -643,7 +643,7 @@ if(UNIX)
+#        if(NOT APPLE)
+#          CHECK_INCLUDE_FILE(pthread.h HAVE_PTHREAD)
+#          if(ANDROID)
+#     -      set(OPENCV_LINKER_LIBS ${OPENCV_LINKER_LIBS} dl m log)
+#     +      set(OPENCV_LINKER_LIBS ${OPENCV_LINKER_LIBS} dl m log z)
+#          elseif(CMAKE_SYSTEM_NAME MATCHES "FreeBSD|NetBSD|DragonFly|OpenBSD|Haiku")
+#            set(OPENCV_LINKER_LIBS ${OPENCV_LINKER_LIBS} m pthread)
+#          elseif(EMSCRIPTEN)
     
-    ```
+# ```
+```
 
-* build for host
+- build for host
 
-  * ```
-    cd root_dir_of_opencv
-    mkdir -p build/install
-    cd build
-    cmake -DBUILD_JAVA=OFF -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$PWD/install 
-    make install -j32
-    ```
+```shell
+cd root_dir_of_opencv
+mkdir -p build/install
+cd build
+cmake -DBUILD_JAVA=OFF -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$PWD/install 
+make install -j32
+```
 
 * build for android-aarch64
 
-  * ```
-    cd root_dir_of_opencv
-    mkdir -p build_android/install
-    cd build_android
-    
-    cmake -DCMAKE_TOOLCHAIN_FILE="$NDK_ROOT/build/cmake/android.toolchain.cmake" -DANDROID_NDK="$NDK_ROOT"  -DANDROID_ABI=arm64-v8a -DANDROID_NATIVE_API_LEVEL=21 -DBUILD_JAVA=OFF -DBUILD_ANDROID_PROJECTS=OFF -DBUILD_ANDROID_EXAMPLES=OFF -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$PWD/install ..
-    
-    make install -j32
-    ```
+```shell
+cd root_dir_of_opencv
+mkdir -p build_android/install
+cd build_android
+
+cmake -DCMAKE_TOOLCHAIN_FILE="$NDK_ROOT/build/cmake/android.toolchain.cmake" -DANDROID_NDK="$NDK_ROOT"  -DANDROID_ABI=arm64-v8a -DANDROID_NATIVE_API_LEVEL=21 -DBUILD_JAVA=OFF -DBUILD_ANDROID_PROJECTS=OFF -DBUILD_ANDROID_EXAMPLES=OFF -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$PWD/install ..
+
+make install -j32
+```
 
 * after build OpenCV, you need export  `OPENCV_INSTALL_INCLUDE_PATH ` and `OPENCV_INSTALL_LIB_PATH`
 
-  * host build: 
-    * export OPENCV_INSTALL_INCLUDE_PATH=${path of opencv}/build/install/include
-    * export OPENCV_INSTALL_LIB_PATH=${path of opencv}/build/install/lib
-  * cross build for android aarch64:
-    * export OPENCV_INSTALL_INCLUDE_PATH=${path of opencv}/build_android/install/sdk/native/jni/include
-    * export OPENCV_INSTALL_LIB_PATH=${path of opencv}/build_android/install/sdk/native/libs/arm64-v8a
+```shell
+# host build: 
+export OPENCV_INSTALL_INCLUDE_PATH=${path of opencv}/build/install/include
+export OPENCV_INSTALL_LIB_PATH=${path of opencv}/build/install/lib
+# or cross build for android aarch64:
+export OPENCV_INSTALL_INCLUDE_PATH=${path of opencv}/build_android/install/sdk/native/jni/include
+export OPENCV_INSTALL_LIB_PATH=${path of opencv}/build_android/install/sdk/native/libs/arm64-v8a
+```
 
 ###  Step4: build test demo
 
- * run build.sh
-    * host:
-       * export CXX=g++
-       * ./build.sh
-   * cross android aarch64
-     *  export CXX=aarch64-linux-android21-clang++
-     * ./build.sh
+```shell
+run build.sh
+
+# if host:
+export CXX=g++
+./build.sh
+# or cross android aarch64
+export CXX=aarch64-linux-android21-clang++
+./build.sh
+```
 
 ### Step5: run demo
 
@@ -99,30 +122,38 @@ Cpp file compile of YOLOX object detection base on [MegEngine](https://github.co
 > * reference to python demo's `dump.py` script.
 > * wget https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_s.mge
 
-* host:
-  * LD_LIBRARY_PATH=$MGE_INSTALL_PATH/lib/:$OPENCV_INSTALL_LIB_PATH ./yolox yolox_s.mge ../../../assets/dog.jpg cuda/cpu/multithread <warmup_count> <thread_number>
-* cross android
-  * adb push/scp $MGE_INSTALL_PATH/lib/libmegengine.so android_phone
-  * adb push/scp $OPENCV_INSTALL_LIB_PATH/*.so android_phone
-  * adb push/scp ./yolox yolox_s.mge android_phone
-  * adb push/scp ../../../assets/dog.jpg android_phone
-  * login in android_phone by adb or ssh
-    * then run: LD_LIBRARY_PATH=. ./yolox yolox_s.mge dog.jpg cpu/multithread <warmup_count> <thread_number> <use_fast_run> <use_weight_preprocess>  <run_with_fp16>
-      * <warmup_count> means warmup count, valid number >=0
-      * <thread_number> means thread number, valid number >=1, only take effect `multithread` device
-      * <use_fast_run> if >=1 , will use fastrun to choose best algo
-      * <use_weight_preprocess> if >=1, will handle weight preprocess before exe
-      * <run_with_fp16> if >=1, will run with fp16 mode
+```shell
+# if host:
+LD_LIBRARY_PATH=$MGE_INSTALL_PATH/lib/:$OPENCV_INSTALL_LIB_PATH ./yolox yolox_s.mge ../../../assets/dog.jpg cuda/cpu/multithread <warmup_count> <thread_number>
+
+# or cross android
+adb push/scp $MGE_INSTALL_PATH/lib/libmegengine.so android_phone
+adb push/scp $OPENCV_INSTALL_LIB_PATH/*.so android_phone
+adb push/scp ./yolox yolox_s.mge android_phone
+adb push/scp ../../../assets/dog.jpg android_phone
+
+# login in android_phone by adb or ssh
+# then run: 
+LD_LIBRARY_PATH=. ./yolox yolox_s.mge dog.jpg cpu/multithread <warmup_count> <thread_number> <use_fast_run> <use_weight_preprocess>  <run_with_fp16>
+
+# * <warmup_count> means warmup count, valid number >=0
+# * <thread_number> means thread number, valid number >=1, only take effect `multithread` device
+# * <use_fast_run> if >=1 , will use fastrun to choose best algo
+# * <use_weight_preprocess> if >=1, will handle weight preprocess before exe
+# * <run_with_fp16> if >=1, will run with fp16 mode
+```
 
 ## Bechmark
 
-*  model info: yolox-s @ input(1,3,640,640)					
+* model info: yolox-s @ input(1,3,640,640)					
 
 * test devices
 
+```
   * x86_64  -- Intel(R) Xeon(R) CPU E5-2620 v4 @ 2.10GHz					
   * aarch64 -- xiamo phone mi9					
   * cuda    -- 1080TI @ cuda-10.1-cudnn-v7.6.3-TensorRT-6.0.1.5.sh @ Intel(R) Xeon(R) CPU E5-2620 v4 @ 2.10GHz
+```
 
   | megengine @ tag1.4(fastrun + weight\_preprocess)/sec | 1 thread |
   | ---------------------------------------------------- | -------- |

demo/ONNXRuntime/README.md

@@ -3,6 +3,7 @@
 This doc introduces how to convert your pytorch model into onnx, and how to run an onnxruntime demo to verify your convertion.
 
 ### Download ONNX models.
+
 | Model | Parameters | GFLOPs | Test Size | mAP | Weights |
 |:------| :----: | :----: | :---: | :---: | :---: |
 |  YOLOX-Nano |  0.91M  | 1.08 | 416x416 | 25.3 | [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EfAGwvevU-lNhW5OqFAyHbwBJdI_7EaKu5yU04fgF5BU7w?e=gvq4hf)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_nano.onnx) |
@@ -29,7 +30,7 @@ python3 tools/export_onnx.py --output-name yolox_s.onnx -n yolox-s -c yolox_s.pt
 Notes:
 * -n: specify a model name. The model name must be one of the [yolox-s,m,l,x and yolox-nane, yolox-tiny, yolov3]
 * -c: the model you have trained
-* -o: opset version, default 11. **However, if you will further convert your onnx model to [OpenVINO](../OpenVINO/), please specify the opset version to 10.**
+* -o: opset version, default 11. **However, if you will further convert your onnx model to [OpenVINO](https://github.com/Megvii-BaseDetection/YOLOX/demo/OpenVINO/), please specify the opset version to 10.**
 * --no-onnxsim: disable onnxsim
 * To customize an input shape for onnx model,  modify the following code in tools/export.py:
 

demo/OpenVINO/cpp/README.md

@@ -3,6 +3,7 @@
 This toturial includes a C++ demo for OpenVINO, as well as some converted models.
 
 ### Download OpenVINO models.
+
 | Model | Parameters | GFLOPs | Test Size | mAP | Weights |
 |:------| :----: | :----: | :---: | :---: | :---: |
 |  [YOLOX-Nano](../../../exps/nano.py) |  0.91M  | 1.08 | 416x416 | 25.3 | [Download](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EeWY57o5wQZFtXYd1KJw6Z8B4vxZru649XxQHYIFgio3Qw?e=ZS81ce)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_nano_openvino.tar.gz) |

demo/OpenVINO/python/README.md

@@ -3,6 +3,7 @@
 This toturial includes a Python demo for OpenVINO, as well as some converted models.
 
 ### Download OpenVINO models.
+
 | Model | Parameters | GFLOPs | Test Size | mAP | Weights |
 |:------| :----: | :----: | :---: | :---: | :---: |
 |  [YOLOX-Nano](../../../exps/default/nano.py) |  0.91M  | 1.08 | 416x416 | 25.3 | [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EeWY57o5wQZFtXYd1KJw6Z8B4vxZru649XxQHYIFgio3Qw?e=ZS81ce)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_nano_openvino.tar.gz) |
@@ -51,7 +52,7 @@ source ~/.bashrc
 
 1. Export ONNX model
 
-   Please refer to the [ONNX toturial](../../ONNXRuntime). **Note that you should set --opset to 10, otherwise your next step will fail.**
+   Please refer to the [ONNX toturial](https://github.com/Megvii-BaseDetection/YOLOX/demo/ONNXRuntime). **Note that you should set --opset to 10, otherwise your next step will fail.**
 
 2. Convert ONNX to OpenVINO
 

demo/TensorRT/cpp/README.md

@@ -6,7 +6,7 @@ our C++ demo does not include the model converting or constructing like other te
 
 ## Step 1: Prepare serialized engine file
 
-Follow the trt [python demo README](../python/README.md) to convert and save the serialized engine file.
+Follow the trt [python demo README](https://github.com/Megvii-BaseDetection/YOLOX/demo/TensorRT/python/README.md) to convert and save the serialized engine file.
 
 Check the 'model_trt.engine' file generated from Step 1, which will be automatically saved at the current demo dir.
 

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+# Copyright (c) Facebook, Inc. and its affiliates.
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ * some extra css to make markdown look similar between github/sphinx
+ */
+
+/*
+ * Below is for install.md:
+ */
+ .rst-content code {
+    white-space: pre;
+    border: 0px;
+  }
+  
+  .rst-content th {
+    border: 1px solid #e1e4e5;
+  }
+  
+  .rst-content th p {
+    /* otherwise will be default 24px for regular paragraph */
+    margin-bottom: 0px;
+  }
+  
+  .rst-content .line-block {
+    /* otherwise will be 24px */
+    margin-bottom: 0px;
+  }
+  
+  div.section > details {
+    padding-bottom: 1em;
+  }
+  

docs/conf.py

@@ -0,0 +1,384 @@
+# -*- coding: utf-8 -*-
+# Code are based on
+# https://github.com/facebookresearch/detectron2/blob/master/docs/conf.py
+# Copyright (c) Facebook, Inc. and its affiliates.
+# Copyright (c) Megvii, Inc. and its affiliates.
+
+# flake8: noqa
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+from unittest import mock
+from sphinx.domains import Domain
+from typing import Dict, List, Tuple
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+import sphinx_rtd_theme
+
+
+class GithubURLDomain(Domain):
+    """
+    Resolve certain links in markdown files to github source.
+    """
+
+    name = "githuburl"
+    ROOT = "https://github.com/Megvii-BaseDetection/YOLOX"
+    # LINKED_DOC = ["tutorials/install", "tutorials/getting_started"]
+    LINKED_DOC = ["tutorials/install",]
+
+    def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):
+        github_url = None
+        if not target.endswith("html") and target.startswith("../../"):
+            url = target.replace("../", "")
+            github_url = url
+        if fromdocname in self.LINKED_DOC:
+            # unresolved links in these docs are all github links
+            github_url = target
+
+        if github_url is not None:
+            if github_url.endswith("MODEL_ZOO") or github_url.endswith("README"):
+                # bug of recommonmark.
+                # https://github.com/readthedocs/recommonmark/blob/ddd56e7717e9745f11300059e4268e204138a6b1/recommonmark/parser.py#L152-L155
+                github_url += ".md"
+            print("Ref {} resolved to github:{}".format(target, github_url))
+            contnode["refuri"] = self.ROOT + github_url
+            return [("githuburl:any", contnode)]
+        else:
+            return []
+
+
+# to support markdown
+from recommonmark.parser import CommonMarkParser
+
+sys.path.insert(0, os.path.abspath("../"))
+os.environ["_DOC_BUILDING"] = "True"
+DEPLOY = os.environ.get("READTHEDOCS") == "True"
+
+
+# -- Project information -----------------------------------------------------
+
+# fmt: off
+try:
+    import torch  # noqa
+except ImportError:
+    for m in [
+        "torch", "torchvision", "torch.nn", "torch.nn.parallel", "torch.distributed", "torch.multiprocessing", "torch.autograd",
+        "torch.autograd.function", "torch.nn.modules", "torch.nn.modules.utils", "torch.utils", "torch.utils.data", "torch.onnx",
+        "torchvision", "torchvision.ops",
+    ]:
+        sys.modules[m] = mock.Mock(name=m)
+    sys.modules['torch'].__version__ = "1.7"  # fake version
+    HAS_TORCH = False
+else:
+    try:
+        torch.ops.yolox = mock.Mock(name="torch.ops.yolox")
+    except:
+        pass
+    HAS_TORCH = True
+
+for m in [
+    "cv2", "scipy", "portalocker", "yolox._C",
+    "pycocotools", "pycocotools.mask", "pycocotools.coco", "pycocotools.cocoeval",
+    "google", "google.protobuf", "google.protobuf.internal", "onnx",
+    "caffe2", "caffe2.proto", "caffe2.python", "caffe2.python.utils", "caffe2.python.onnx", "caffe2.python.onnx.backend",
+]:
+    sys.modules[m] = mock.Mock(name=m)
+# fmt: on
+sys.modules["cv2"].__version__ = "3.4"
+
+import yolox  # isort: skip
+
+# if HAS_TORCH:
+#     from detectron2.utils.env import fixup_module_metadata
+
+#     fixup_module_metadata("torch.nn", torch.nn.__dict__)
+#     fixup_module_metadata("torch.utils.data", torch.utils.data.__dict__)
+
+
+project = "YOLOX"
+copyright = "2021-2021, YOLOX contributors"
+author = "YOLOX contributors"
+
+# The short X.Y version
+version = yolox.__version__
+# The full version, including alpha/beta/rc tags
+release = version
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+needs_sphinx = "3.0"
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "recommonmark",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    'sphinx_markdown_tables',
+]
+
+# -- Configurations for plugins ------------
+napoleon_google_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_special_with_doc = True
+napoleon_numpy_docstring = False
+napoleon_use_rtype = False
+autodoc_inherit_docstrings = False
+autodoc_member_order = "bysource"
+
+if DEPLOY:
+    intersphinx_timeout = 10
+else:
+    # skip this when building locally
+    intersphinx_timeout = 0.5
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.6", None),
+    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
+    "torch": ("https://pytorch.org/docs/master/", None),
+}
+# -------------------------
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+source_suffix = [".rst", ".md"]
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "build", "README.md", "tutorials/README.md"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "yoloxdoc"
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, "yolox.tex", "yolox Documentation", "yolox contributors", "manual")
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, "YOLOX", "YOLOX Documentation", [author], 1)]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "YOLOX",
+        "YOLOX Documentation",
+        author,
+        "YOLOX",
+        "One line description of project.",
+        "Miscellaneous",
+    )
+]
+
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    # we hide something deliberately
+    if getattr(obj, "__HIDE_SPHINX_DOC__", False):
+        return True
+
+    # Hide some that are deprecated or not intended to be used
+    HIDDEN = {
+        "ResNetBlockBase",
+        "GroupedBatchSampler",
+        "build_transform_gen",
+        "export_caffe2_model",
+        "export_onnx_model",
+        "apply_transform_gens",
+        "TransformGen",
+        "apply_augmentations",
+        "StandardAugInput",
+        "build_batch_data_loader",
+        "draw_panoptic_seg_predictions",
+        "WarmupCosineLR",
+        "WarmupMultiStepLR",
+    }
+    try:
+        if name in HIDDEN or (
+            hasattr(obj, "__doc__") and obj.__doc__.lower().strip().startswith("deprecated")
+        ):
+            print("Skipping deprecated object: {}".format(name))
+            return True
+    except:
+        pass
+    return skip
+
+
+# _PAPER_DATA = {
+#     "resnet": ("1512.03385", "Deep Residual Learning for Image Recognition"),
+#     "fpn": ("1612.03144", "Feature Pyramid Networks for Object Detection"),
+#     "mask r-cnn": ("1703.06870", "Mask R-CNN"),
+#     "faster r-cnn": (
+#         "1506.01497",
+#         "Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks",
+#     ),
+#     "deformconv": ("1703.06211", "Deformable Convolutional Networks"),
+#     "deformconv2": ("1811.11168", "Deformable ConvNets v2: More Deformable, Better Results"),
+#     "panopticfpn": ("1901.02446", "Panoptic Feature Pyramid Networks"),
+#     "retinanet": ("1708.02002", "Focal Loss for Dense Object Detection"),
+#     "cascade r-cnn": ("1712.00726", "Cascade R-CNN: Delving into High Quality Object Detection"),
+#     "lvis": ("1908.03195", "LVIS: A Dataset for Large Vocabulary Instance Segmentation"),
+#     "rrpn": ("1703.01086", "Arbitrary-Oriented Scene Text Detection via Rotation Proposals"),
+#     "imagenet in 1h": ("1706.02677", "Accurate, Large Minibatch SGD: Training ImageNet in 1 Hour"),
+#     "xception": ("1610.02357", "Xception: Deep Learning with Depthwise Separable Convolutions"),
+#     "mobilenet": (
+#         "1704.04861",
+#         "MobileNets: Efficient Convolutional Neural Networks for Mobile Vision Applications",
+#     ),
+#     "deeplabv3+": (
+#         "1802.02611",
+#         "Encoder-Decoder with Atrous Separable Convolution for Semantic Image Segmentation",
+#     ),
+#     "dds": ("2003.13678", "Designing Network Design Spaces"),
+#     "scaling": ("2103.06877", "Fast and Accurate Model Scaling"),
+# }
+
+
+# def paper_ref_role(
+#     typ: str,
+#     rawtext: str,
+#     text: str,
+#     lineno: int,
+#     inliner,
+#     options: Dict = {},
+#     content: List[str] = [],
+# ):
+#     """
+#     Parse :paper:`xxx`. Similar to the "extlinks" sphinx extension.
+#     """
+#     from docutils import nodes, utils
+#     from sphinx.util.nodes import split_explicit_title
+
+#     text = utils.unescape(text)
+#     has_explicit_title, title, link = split_explicit_title(text)
+#     link = link.lower()
+#     if link not in _PAPER_DATA:
+#         inliner.reporter.warning("Cannot find paper " + link)
+#         paper_url, paper_title = "#", link
+#     else:
+#         paper_url, paper_title = _PAPER_DATA[link]
+#         if "/" not in paper_url:
+#             paper_url = "https://arxiv.org/abs/" + paper_url
+#     if not has_explicit_title:
+#         title = paper_title
+#     pnode = nodes.reference(title, title, internal=False, refuri=paper_url)
+#     return [pnode], []
+
+
+def setup(app):
+    from recommonmark.transform import AutoStructify
+
+    app.add_domain(GithubURLDomain)
+    app.connect("autodoc-skip-member", autodoc_skip_member)
+    # app.add_role("paper", paper_ref_role)
+    app.add_config_value(
+        "recommonmark_config",
+        {"enable_math": True, "enable_inline_math": True, "enable_eval_rst": True},
+        True,
+    )
+    app.add_transform(AutoStructify)

docs/demo/megengine_cpp_readme.md

@@ -0,0 +1 @@
+../../demo/MegEngine/cpp/README.md

docs/demo/megengine_py_readme.md

@@ -0,0 +1 @@
+../../demo/MegEngine/python/README.md

docs/demo/ncnn_android_readme.md

@@ -0,0 +1 @@
+../../demo/ncnn/android/README.md

docs/demo/ncnn_cpp_readme.md

@@ -0,0 +1 @@
+../../demo/ncnn/cpp/README.md

docs/demo/onnx_readme.md

@@ -0,0 +1 @@
+../../demo/ONNXRuntime/README.md

docs/demo/openvino_cpp_readme.md

@@ -0,0 +1 @@
+../../demo/OpenVINO/cpp/README.md

docs/demo/openvino_py_readme.md

@@ -0,0 +1 @@
+../../demo/OpenVINO/python/README.md

docs/demo/trt_cpp_readme.md

@@ -0,0 +1 @@
+../../demo/TensorRT/cpp/README.md

docs/demo/trt_py_readme.md

@@ -0,0 +1 @@
+../../demo/TensorRT/python/README.md

docs/index.rst

@@ -0,0 +1,32 @@
+
+Welcome to YOLOX's documentation!
+======================================
+
+.. image:: ../assets/logo.png
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Quick Run
+   
+   quick_run
+   model_zoo
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   train_custom_data
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Demployment
+
+   demo/trt_py_readme
+   demo/trt_cpp_readme
+   demo/megengine_cpp_readme
+   demo/megengine_py_readme
+   demo/ncnn_android_readme
+   demo/ncnn_cpp_readme
+   demo/onnx_readme
+   demo/openvino_py_readme
+   demo/openvino_cpp_readme

docs/model_zoo.md

@@ -0,0 +1,18 @@
+# Model Zoo
+
+## Standard Models.
+
+|Model |size |mAP<sup>test<br>0.5:0.95 | Speed V100<br>(ms) | Params<br>(M) |FLOPs<br>(G)| weights |
+| ------        |:---: | :---:       |:---:     |:---:  | :---: | :----: |
+|[YOLOX-s](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/default/yolox_s.py)    |640  |39.6      |9.8     |9.0 | 26.8 | [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EW62gmO2vnNNs5npxjzunVwB9p307qqygaCkXdTO88BLUg?e=NMTQYw)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_s.pth) |
+|[YOLOX-m](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/default/yolox_m.py)    |640  |46.4      |12.3     |25.3 |73.8| [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/ERMTP7VFqrVBrXKMU7Vl4TcBQs0SUeCT7kvc-JdIbej4tQ?e=1MDo9y)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_m.pth) |
+|[YOLOX-l](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/default/yolox_l.py)    |640  |50.0  |14.5 |54.2| 155.6 | [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EWA8w_IEOzBKvuueBqfaZh0BeoG5sVzR-XYbOJO4YlOkRw?e=wHWOBE)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_l.pth) |
+|[YOLOX-x](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/default/yolox_x.py)   |640  |**51.2**      | 17.3 |99.1 |281.9 | [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EdgVPHBziOVBtGAXHfeHI5kBza0q9yyueMGdT0wXZfI1rQ?e=tABO5u)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_x.pth) |
+|[YOLOX-Darknet53](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/default/yolov3.py)   |640  | 47.4      | 11.1 |63.7 | 185.3 | [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EZ-MV1r_fMFPkPrNjvbJEMoBLOLAnXH-XKEB77w8LhXL6Q?e=mf6wOc)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_darknet53.pth) |
+
+## Light Models.
+
+|Model |size |mAP<sup>val<br>0.5:0.95 | Params<br>(M) |FLOPs<br>(G)| weights |
+| ------        |:---:  |  :---:       |:---:     |:---:  | :---: |
+|[YOLOX-Nano](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/default/nano.py) |416  |25.3  | 0.91 |1.08 | [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EdcREey-krhLtdtSnxolxiUBjWMy6EFdiaO9bdOwZ5ygCQ?e=yQpdds)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_nano.pth) |
+|[YOLOX-Tiny](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/default/yolox_tiny.py) |416  |32.8 | 5.06 |6.45 | [onedrive](https://megvii-my.sharepoint.cn/:u:/g/personal/gezheng_megvii_com/EbZuinX5X1dJmNy8nqSRegABWspKw3QpXxuO82YSoFN1oQ?e=Q7V7XE)/[github](https://github.com/Megvii-BaseDetection/storage/releases/download/0.0.1/yolox_tiny_32dot8.pth) |

docs/quick_run.md

@@ -0,0 +1,101 @@
+
+# Get Started
+
+## 1.Installation
+
+Step1. Install YOLOX.
+```shell
+git clone [email protected]:Megvii-BaseDetection/YOLOX.git
+cd YOLOX
+pip3 install -U pip && pip3 install -r requirements.txt
+pip3 install -v -e .  # or  python3 setup.py develop
+```
+Step2. Install [apex](https://github.com/NVIDIA/apex).
+
+```shell
+# skip this step if you don't want to train model.
+git clone https://github.com/NVIDIA/apex
+cd apex
+pip3 install -v --disable-pip-version-check --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" ./
+```
+Step3. Install [pycocotools](https://github.com/cocodataset/cocoapi).
+
+```shell
+pip3 install cython; pip3 install 'git+https://github.com/cocodataset/cocoapi.git#subdirectory=PythonAPI'
+```
+
+## 2.Demo
+
+Step1. Download a pretrained model from the benchmark table.
+
+Step2. Use either -n or -f to specify your detector's config. For example:
+
+```shell
+python tools/demo.py image -n yolox-s -c /path/to/your/yolox_s.pth --path assets/dog.jpg --conf 0.25 --nms 0.45 --tsize 640 --save_result --device [cpu/gpu]
+```
+or
+```shell
+python tools/demo.py image -f exps/default/yolox_s.py -c /path/to/your/yolox_s.pth --path assets/dog.jpg --conf 0.25 --nms 0.45 --tsize 640 --save_result --device [cpu/gpu]
+```
+Demo for video:
+```shell
+python tools/demo.py video -n yolox-s -c /path/to/your/yolox_s.pth --path /path/to/your/video --conf 0.25 --nms 0.45 --tsize 640 --save_result --device [cpu/gpu]
+```
+
+
+## 3.Reproduce our results on COCO
+
+Step1. Prepare COCO dataset
+```shell
+cd <YOLOX_HOME>
+ln -s /path/to/your/COCO ./datasets/COCO
+```
+
+Step2. Reproduce our results on COCO by specifying -n:
+
+```shell
+python tools/train.py -n yolox-s -d 8 -b 64 --fp16 -o
+                         yolox-m
+                         yolox-l
+                         yolox-x
+```
+* -d: number of gpu devices
+* -b: total batch size, the recommended number for -b is num-gpu * 8
+* --fp16: mixed precision training
+
+**Multi Machine Training**
+
+We also support multi-nodes training. Just add the following args:
+* --num\_machines: num of your total training nodes
+* --machine\_rank: specify the rank of each node
+
+When using -f, the above commands are equivalent to:
+
+```shell
+python tools/train.py -f exps/default/yolox-s.py -d 8 -b 64 --fp16 -o
+                         exps/default/yolox-m.py
+                         exps/default/yolox-l.py
+                         exps/default/yolox-x.py
+```
+
+## 4.Evaluation
+
+We support batch testing for fast evaluation:
+
+```shell
+python tools/eval.py -n  yolox-s -c yolox_s.pth -b 64 -d 8 --conf 0.001 [--fp16] [--fuse]
+                         yolox-m
+                         yolox-l
+                         yolox-x
+```
+* --fuse: fuse conv and bn
+* -d: number of GPUs used for evaluation. DEFAULT: All GPUs available will be used.
+* -b: total batch size across on all GPUs
+
+To reproduce speed test, we use the following command:
+```shell
+python tools/eval.py -n  yolox-s -c yolox_s.pth -b 1 -d 1 --conf 0.001 --fp16 --fuse
+                         yolox-m
+                         yolox-l
+                         yolox-x
+```

docs/requirements-doc.txt

@@ -0,0 +1,8 @@
+docutils==0.16
+# https://github.com/sphinx-doc/sphinx/commit/7acd3ada3f38076af7b2b5c9f3b60bb9c2587a3d
+sphinx==3.2.0
+recommonmark==0.6.0
+sphinx_rtd_theme
+omegaconf>=2.1.0.dev24
+hydra-core>=1.1.0.dev5
+sphinx-markdown-tables==0.0.15

docs/train_custom_data.md

@@ -1,17 +1,18 @@
-# Train Custom Data.
+# Train Custom Data
+
 This page explains how to train your own custom data with YOLOX.
 
 We take an example of fine-tuning YOLOX-S model on VOC dataset to give a more clear guide.
 
 ## 0. Before you start
-Clone this repo and follow the [README](../README.md) to install YOLOX.
+Clone this repo and follow the [README](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/README.md) to install YOLOX.
 
 ## 1. Create your own dataset
 **Step 1** Prepare your own dataset with images and labels first. For labeling images, you can use tools like [Labelme](https://github.com/wkentaro/labelme) or [CVAT](https://github.com/openvinotoolkit/cvat).
 
 **Step 2** Then, you should write the corresponding Dataset Class which can load images and labels through `__getitem__` method. We currently support COCO format and VOC format.
 
-You can also write the Dataset by your own. Let's take the [VOC](../yolox/data/datasets/voc.py#L151) Dataset file for example:
+You can also write the Dataset by your own. Let's take the [VOC](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/yolox/data/datasets/voc.py#L151) Dataset file for example:
 ```python
     @Dataset.resize_getitem
     def __getitem__(self, index):
@@ -23,9 +24,9 @@ You can also write the Dataset by your own. Let's take the [VOC](../yolox/data/d
         return img, target, img_info, img_id
 ```
 
-One more thing worth noting is that you should also implement [pull_item](../yolox/data/datasets/voc.py#L129) and [load_anno](../yolox/data/datasets/voc.py#L121) method for the `Mosiac` and `MixUp` augmentations.
+One more thing worth noting is that you should also implement [pull_item](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/yolox/data/datasets/voc.py#L129) and [load_anno](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/yolox/data/datasets/voc.py#L121) method for the `Mosiac` and `MixUp` augmentations.
 
-**Step 3** Prepare the evaluator. We currently have [COCO evaluator](../yolox/evaluators/coco_evaluator.py) and [VOC evaluator](../yolox/evaluators/voc_evaluator.py).
+**Step 3** Prepare the evaluator. We currently have [COCO evaluator](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/yolox/evaluators/coco_evaluator.py) and [VOC evaluator](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/yolox/evaluators/voc_evaluator.py).
 If you have your own format data or evaluation metric, you can write your own evaluator.
 
 **Step 4** Put your dataset under `$YOLOX_DIR/datasets`, for VOC:
@@ -40,9 +41,9 @@ ln -s /path/to/your/VOCdevkit ./datasets/VOCdevkit
 ## 2. Create your Exp file to control everything
 We put everything involved in a model to one single Exp file, including model setting, training setting, and testing setting.
 
-**A complete Exp file is at [yolox_base.py](../yolox/exp/yolox_base.py).** It may be too long to write for every exp, but you can inherit the base Exp file and only overwrite the changed part.
+**A complete Exp file is at [yolox_base.py](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/yolox/exp/base_exp.py).** It may be too long to write for every exp, but you can inherit the base Exp file and only overwrite the changed part.
 
-Let's take the [VOC Exp file](../exps/example/yolox_voc/yolox_voc_s.py) as an example.
+Let's take the [VOC Exp file](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/example/yolox_voc/yolox_voc_s.py) as an example.
 
 We select `YOLOX-S` model here, so we should change the network depth and width. VOC has only 20 classes, so we should also change the `num_classes`.
 
@@ -59,12 +60,12 @@ class Exp(MyExp):
 
 Besides, you should also overwrite the `dataset` and `evaluator`, prepared before training the model on your own data.
 
-Please see [get_data_loader](../exps/example/yolox_voc/yolox_voc_s.py#L20), [get_eval_loader](../exps/example/yolox_voc/yolox_voc_s.py#L82), and [get_evaluator](../exps/example/yolox_voc/yolox_voc_s.py#L113) for more details.
+Please see [get_data_loader](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/example/yolox_voc/yolox_voc_s.py#L20), [get_eval_loader](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/example/yolox_voc/yolox_voc_s.py#L82), and [get_evaluator](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/exps/example/yolox_voc/yolox_voc_s.py#L113) for more details.
 
 ✧✧✧ You can also see the `exps/example/custom` directory for more details.
 
 ## 3. Train
-Except special cases, we always recommend to use our [COCO pretrained weights](../README.md) for initializing the model.
+Except special cases, we always recommend to use our [COCO pretrained weights](https://github.com/Megvii-BaseDetection/YOLOX/blob/main/README.md) for initializing the model.
 
 Once you get the Exp file and the COCO pretrained weights we provided, you can train your own model by the following below command:
 ```bash