update documentation build

Megvii-BaseDetection · Jul 28, 2021 · f60eb1d · f60eb1d
1 parent 5945f9c
commit f60eb1d
Show file tree

Hide file tree

Showing 21 changed files with 605 additions and 83 deletions.
diff --git a/demo/MegEngine/cpp/README.md b/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 |
   | ---------------------------------------------------- | -------- |

diff --git a/demo/ONNXRuntime/README.md b/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:
 

diff --git a/demo/OpenVINO/cpp/README.md b/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) |

diff --git a/demo/OpenVINO/python/README.md b/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
 

diff --git a/demo/TensorRT/cpp/README.md b/demo/TensorRT/cpp/README.md
@@ -6,7 +6,7 @@ our C++ demo will 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 automatically saved at the current demo dir.
 

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_build
diff --git a/docs/Makefile b/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)
diff --git a/docs/_static/css/custom.css b/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;
+  }
+