[Docs] Improve docs style (#879)

* Improve docs style

* update lists

* update the size of image

* modify duplicate mmdet3d

.github/CONTRIBUTING.md

@@ -12,11 +12,12 @@ All kinds of contributions are welcome, including but not limited to the followi
 3. commit your changes
 4. create a PR
 
-Note
+:::{note}
 
 - If you plan to add some new features that involve large changes, it is encouraged to open an issue for discussion first.
 - If you are the author of some papers and would like to include your method to mmsegmentation,
   please contact Kai Chen (chenkaidev[at]gmail[dot]com). We will much appreciate your contribution.
+:::
 
 ## Code style
 

configs/deeplabv3/README.md

@@ -15,7 +15,9 @@
 
 ## Results and models
 
-Note: `D-8` here corresponding to the output stride 8 setting for DeepLab series.
+:::{note}
+`D-8` here corresponding to the output stride 8 setting for DeepLab series.
+:::
 
 ### Cityscapes
 

configs/deeplabv3plus/README.md

@@ -15,9 +15,10 @@
 
 ## Results and models
 
-Note:
+:::{note}
 `D-8`/`D-16` here corresponding to the output stride 8/16 setting for DeepLab series.
 `MG-124` stands for multi-grid dilation in the last stage of ResNet.
+:::
 
 ### Cityscapes
 

docs/_static/css/readthedocs.css

@@ -0,0 +1,6 @@
+.header-logo {
+    background-image: url("../images/mmsegmentation.png");
+    background-size: 201px 40px;
+    height: 40px;
+    width: 201px;
+}

docs/api.rst

@@ -1,6 +1,3 @@
-API Reference
-==============
-
 mmseg.apis
 --------------
 .. automodule:: mmseg.apis

docs/conf.py

@@ -15,6 +15,8 @@ import os
 import subprocess
 import sys
 
+import pytorch_sphinx_theme
+
 sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
@@ -40,11 +42,8 @@ release = get_version()
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
+    'sphinx_markdown_tables', 'sphinx_copybutton', 'myst_parser'
-    'sphinx.ext.viewcode',
-    'recommonmark',
-    'sphinx_markdown_tables',
 ]
 
 autodoc_mock_imports = [
@@ -75,12 +74,101 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_rtd_theme'
+html_theme = 'pytorch_sphinx_theme'
+html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()]
+html_theme_options = {
+    # 'logo_url': 'https://mmsegmentation.readthedocs.io/en/latest/',
+    'menu': [
+        {
+            'name':
+            'Tutorial',
+            'url':
+            'https://github.com/open-mmlab/mmsegmentation/blob/master/'
+            'demo/MMSegmentation_Tutorial.ipynb'
+        },
+        {
+            'name': 'GitHub',
+            'url': 'https://github.com/open-mmlab/mmsegmentation'
+        },
+        {
+            'name':
+            'Upstream',
+            'children': [
+                {
+                    'name': 'MMCV',
+                    'url': 'https://github.com/open-mmlab/mmcv',
+                    'description': 'Foundational library for computer vision'
+                },
+            ]
+        },
+        {
+            'name':
+            'Projects',
+            'children': [
+                {
+                    'name': 'MMAction2',
+                    'url': 'https://github.com/open-mmlab/mmaction2',
+                },
+                {
+                    'name': 'MMClassification',
+                    'url': 'https://github.com/open-mmlab/mmclassification',
+                },
+                {
+                    'name': 'MMOCR',
+                    'url': 'https://github.com/open-mmlab/mmocr',
+                },
+                {
+                    'name': 'MMDetection',
+                    'url': 'https://github.com/open-mmlab/mmdetection',
+                },
+                {
+                    'name': 'MMEditing',
+                    'url': 'https://github.com/open-mmlab/mmediting',
+                },
+                {
+                    'name': 'MMDetection3D',
+                    'url': 'https://github.com/open-mmlab/mmdetection3d',
+                },
+                {
+                    'name': 'MMPose',
+                    'url': 'https://github.com/open-mmlab/mmpose',
+                },
+                {
+                    'name': 'MMTracking',
+                    'url': 'https://github.com/open-mmlab/mmtracking',
+                },
+                {
+                    'name': 'MMGeneration',
+                    'url': 'https://github.com/open-mmlab/mmgeneration',
+                },
+            ]
+        },
+        {
+            'name':
+            'OpenMMLab',
+            'children': [
+                {
+                    'name': 'Homepage',
+                    'url': 'https://openmmlab.com/'
+                },
+                {
+                    'name': 'GitHub',
+                    'url': 'https://github.com/open-mmlab/'
+                },
+            ]
+        },
+    ]
+}
 
 # 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/readthedocs.css']
+
+# Enable ::: for my_st
+myst_enable_extensions = ['colon_fence']
 
 language = 'en'
 

docs/get_started.md

@@ -26,8 +26,10 @@ The compatible MMSegmentation and MMCV versions are as below. Please install the
 | 0.7.0               | mmcv-full>=1.1.2, <1.2.0 |
 | 0.6.0               | mmcv-full>=1.1.2, <1.2.0 |
 
-Note: You need to run `pip uninstall mmcv` first if you have mmcv installed.
+:::{note}
+You need to run `pip uninstall mmcv` first if you have mmcv installed.
 If mmcv and mmcv-full are both installed, there will be `ModuleNotFoundError`.
+:::
 
 ## Installation
 
@@ -105,7 +107,7 @@ cd mmsegmentation
 pip install -e .  # or "python setup.py develop"
 ```
 
-Note:
+:::{note}
 
 1. When training or testing models on Windows, please ensure that all the '\\' in paths are replaced with '/'. Add .replace('\\', '/') to your python code wherever path strings occur.
 2. The `version+git_hash` will also be saved in trained models meta, e.g. 0.5.0+c415a2e.
@@ -114,6 +116,7 @@ Note:
    you can install it before installing MMCV.
 5. Some dependencies are optional. Simply running `pip install -e .` will only install the minimum runtime requirements.
    To use optional dependencies like `cityscapessripts`  either install them manually with `pip install -r requirements/optional.txt` or specify desired extras when calling `pip` (e.g. `pip install -e .[optional]`). Valid keys for the extras field are: `all`, `tests`, `build`, and `optional`.
+:::
 
 ### A from-scratch setup script
 

docs/inference.md

@@ -63,8 +63,10 @@ Assume that you have already downloaded the checkpoints to the directory `checkp
         4 --out results.pkl --eval mIoU cityscapes
     ```
 
-   Note: There is some gap (~0.1%) between cityscapes mIoU and our mIoU. The reason is that cityscapes average each class with class size by default.
+ :::{note}
+ There is some gap (~0.1%) between cityscapes mIoU and our mIoU. The reason is that cityscapes average each class with class size by default.
    We use the simple version without average for all datasets.
+:::
 
 5. Test PSPNet on cityscapes test split with 4 GPUs, and generate the png files to be submit to the official evaluation server.
 

docs/model_zoo.md

@@ -176,4 +176,6 @@ The training speed is reported as followed, in terms of second per iter (s/iter)
 | [CASILVision](https://github.com/CSAILVision/semantic-segmentation-pytorch) | 1.15           | N/A          |
 | [vedaseg](https://github.com/Media-Smart/vedaseg)                           | 0.95           | 1.25       |
 
-Note: The output stride of DeepLabV3+ is 8.
+:::{note}
+The output stride of DeepLabV3+ is 8.
+:::

docs/tutorials/customize_datasets.md

@@ -42,8 +42,10 @@ Only
 `data/my_dataset/ann_dir/train/xxx{seg_map_suffix}`,
 `data/my_dataset/ann_dir/train/zzz{seg_map_suffix}` will be loaded.
 
-Note: The annotations are images of shape (H, W), the value pixel should fall in range `[0, num_classes - 1]`.
+:::{note}
+The annotations are images of shape (H, W), the value pixel should fall in range `[0, num_classes - 1]`.
 You may use `'P'` mode of [pillow](https://pillow.readthedocs.io/en/stable/handbook/concepts.html#palette) to create your annotation image with color.
+:::
 
 ## Customize datasets by mixing dataset
 

docs/tutorials/customize_runtime.md

@@ -176,12 +176,14 @@ In such case, we can set the workflow as
 
 so that 1 epoch for training and 1 epoch for validation will be run iteratively.
 
-**Note**:
+:::{note}
 
 1. The parameters of model will not be updated during val epoch.
 2. Keyword `total_epochs` in the config only controls the number of training epochs and will not affect the validation workflow.
 3. Workflows `[('train', 1), ('val', 1)]` and `[('train', 1)]` will not change the behavior of `EvalHook` because `EvalHook` is called by `after_train_epoch` and validation workflow only affect hooks that are called through `after_val_epoch`. Therefore, the only difference between `[('train', 1), ('val', 1)]` and `[('train', 1)]` is that the runner will calculate losses on validation set after each training epoch.
 
+:::
+
 ## Customize hooks
 
 ### Use hooks implemented in MMCV

docs/useful_tools.md

@@ -19,7 +19,9 @@ Params: 48.98 M
 ==============================
 ```
 
-**Note**: This tool is still experimental and we do not guarantee that the number is correct. You may well use the result for simple comparisons, but double check it before you adopt it in technical reports or papers.
+:::{note}
+This tool is still experimental and we do not guarantee that the number is correct. You may well use the result for simple comparisons, but double check it before you adopt it in technical reports or papers.
+:::
 
 (1) FLOPs are related to the input shape while parameters are not. The default input shape is (1, 3, 1280, 800).
 (2) Some operators are not counted into FLOPs like GN and custom operators.
@@ -74,7 +76,9 @@ Description of arguments:
 - `--dynamic-export`: Determines whether to export ONNX model with dynamic input and output shapes. If not specified, it will be set to `False`.
 - `--cfg-options`:Update config options.
 
-**Note**: This tool is still experimental. Some customized operators are not supported for now.
+:::{note}
+This tool is still experimental. Some customized operators are not supported for now.
+:::
 
 ### Evaluate ONNX model
 
@@ -132,7 +136,9 @@ Description of all arguments
 | deeplabv3  |   deeplabv3_r50-d8_769x769_40k_cityscapes.py    | cityscapes |  mIoU  |  78.5   |    78.3     |               |               |
 | deeplabv3+ | deeplabv3plus_r50-d8_769x769_40k_cityscapes.py  | cityscapes |  mIoU  |  78.9   |    78.7     |               |               |
 
-**Note**: TensorRT is only available on configs with `whole mode`.
+:::{note}
+TensorRT is only available on configs with `whole mode`.
+:::
 
 ### Convert to TorchScript (experimental)
 
@@ -158,9 +164,13 @@ Description of arguments:
 - `--show`: Determines whether to print the traced graph of the exported model. If not specified, it will be set to `False`.
 - `--verify`: Determines whether to verify the correctness of an exported model. If not specified, it will be set to `False`.
 
-**Note**: It's only support PyTorch>=1.8.0 for now.
+:::{note}
+It's only support PyTorch>=1.8.0 for now.
+:::
 
-**Note**: This tool is still experimental. Some customized operators are not supported for now.
+:::{note}
+This tool is still experimental. Some customized operators are not supported for now.
+:::
 
 Examples:
 
@@ -211,7 +221,9 @@ Description of all arguments
 - `--verify` : Verify the outputs of ONNXRuntime and TensorRT.
 - `--verbose` : Whether to verbose logging messages while creating TensorRT engine. Defaults to False.
 
-**Note**: Only tested on whole mode.
+:::{note}
+Only tested on whole mode.
+:::
 
 ## Miscellaneous
 
@@ -297,7 +309,9 @@ python tools/mmseg2torchserve.py ${CONFIG_FILE} ${CHECKPOINT_FILE} \
 --model-name ${MODEL_NAME}
 ```
 
-**Note**: ${MODEL_STORE} needs to be an absolute path to a folder.
+:::{note}
+${MODEL_STORE} needs to be an absolute path to a folder.
+:::
 
 ### 2. Build `mmseg-serve` docker image
 

docs_zh-CN/_static/css/readthedocs.css

@@ -0,0 +1,6 @@
+.header-logo {
+    background-image: url("../images/mmsegmentation.png");
+    background-size: 201px 40px;
+    height: 40px;
+    width: 201px;
+}

docs_zh-CN/api.rst

@@ -1,6 +1,3 @@
-API Reference
-==============
-
 mmseg.apis
 --------------
 .. automodule:: mmseg.apis

docs_zh-CN/conf.py

@@ -15,6 +15,8 @@ import os
 import subprocess
 import sys
 
+import pytorch_sphinx_theme
+
 sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
@@ -40,14 +42,13 @@ release = get_version()
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
+    'sphinx_markdown_tables', 'sphinx_copybutton', 'myst_parser'
-    'sphinx.ext.viewcode',
-    'recommonmark',
-    'sphinx_markdown_tables',
 ]
 
-autodoc_mock_imports = ['matplotlib', 'pycocotools', 'mmseg.version']
+autodoc_mock_imports = [
+    'matplotlib', 'pycocotools', 'mmseg.version', 'mmcv.ops'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -73,14 +74,103 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_rtd_theme'
+html_theme = 'pytorch_sphinx_theme'
+html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()]
+html_theme_options = {
+    # 'logo_url': 'https://mmsegmentation.readthedocs.io/en/latest/',
+    'menu': [
+        {
+            'name':
+            'Tutorial',
+            'url':
+            'https://github.com/open-mmlab/mmsegmentation/blob/master/'
+            'demo/MMSegmentation_Tutorial.ipynb'
+        },
+        {
+            'name': 'GitHub',
+            'url': 'https://github.com/open-mmlab/mmsegmentation'
+        },
+        {
+            'name':
+            'Upstream',
+            'children': [
+                {
+                    'name': 'MMCV',
+                    'url': 'https://github.com/open-mmlab/mmcv',
+                    'description': 'Foundational library for computer vision'
+                },
+            ]
+        },
+        {
+            'name':
+            'Projects',
+            'children': [
+                {
+                    'name': 'MMAction2',
+                    'url': 'https://github.com/open-mmlab/mmaction2',
+                },
+                {
+                    'name': 'MMClassification',
+                    'url': 'https://github.com/open-mmlab/mmclassification',
+                },
+                {
+                    'name': 'MMOCR',
+                    'url': 'https://github.com/open-mmlab/mmocr',
+                },
+                {
+                    'name': 'MMDetection',
+                    'url': 'https://github.com/open-mmlab/mmdetection',
+                },
+                {
+                    'name': 'MMEditing',
+                    'url': 'https://github.com/open-mmlab/mmediting',
+                },
+                {
+                    'name': 'MMDetection3D',
+                    'url': 'https://github.com/open-mmlab/mmdetection3d',
+                },
+                {
+                    'name': 'MMPose',
+                    'url': 'https://github.com/open-mmlab/mmpose',
+                },
+                {
+                    'name': 'MMTracking',
+                    'url': 'https://github.com/open-mmlab/mmtracking',
+                },
+                {
+                    'name': 'MMGeneration',
+                    'url': 'https://github.com/open-mmlab/mmgeneration',
+                },
+            ]
+        },
+        {
+            'name':
+            'OpenMMLab',
+            'children': [
+                {
+                    'name': 'Homepage',
+                    'url': 'https://openmmlab.com/'
+                },
+                {
+                    'name': 'GitHub',
+                    'url': 'https://github.com/open-mmlab/'
+                },
+            ]
+        },
+    ]
+}
 
 # 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/readthedocs.css']
 
-language = 'zh_CN'
+# Enable ::: for my_st
+myst_enable_extensions = ['colon_fence']
+
+language = 'zh-CN'
 
 
 def builder_inited_handler(app):

requirements/docs.txt

@@ -1,4 +1,6 @@
-recommonmark
+docutils==0.16.0
+myst-parser
+-e git+https://github.com/gaotongxiao/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
 sphinx==4.0.2
+sphinx_copybutton
 sphinx_markdown_tables
-sphinx_rtd_theme==0.5.2

setup.cfg

@@ -8,6 +8,6 @@ line_length = 79
 multi_line_output = 0
 known_standard_library = setuptools
 known_first_party = mmseg
-known_third_party = PIL,cityscapesscripts,cv2,detail,matplotlib,mmcv,numpy,onnxruntime,packaging,prettytable,pytest,scipy,seaborn,torch,ts
+known_third_party = PIL,cityscapesscripts,cv2,detail,matplotlib,mmcv,numpy,onnxruntime,packaging,prettytable,pytest,pytorch_sphinx_theme,scipy,seaborn,torch,ts
 no_lines_before = STDLIB,LOCALFOLDER
 default_section = THIRDPARTY