[Enhance] Use PyTorch Sphinx Theme (#958)

* [Enhance] Use PyTorch Sphinx Theme * refine English docs * refine Chinese docs * fix type in Chinese docs
open-mmlab · Sep 24, 2021 · 26ab7ff · 26ab7ff
1 parent 75c5c6c
commit 26ab7ff
Show file tree

Hide file tree

Showing 16 changed files with 291 additions and 38 deletions.
diff --git a/docs/_static/css/readthedocs.css b/docs/_static/css/readthedocs.css
@@ -0,0 +1,6 @@
+.header-logo {
+ background-image: url("../image/mmdet3d-logo.png");
+ background-size: 182.5px 40px;
+ height: 40px;
+ width: 182.5px;
+}
diff --git a/docs/_static/image/mmdet3d-logo.png b/docs/_static/image/mmdet3d-logo.png
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,6 +1,3 @@
-API Documentation
-=================
-
 mmdet3d.core
 --------------
 

diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -1,8 +1,4 @@
-# Compatibility with Previous Versions of MMDetection3D
-
-This document provides detailed descriptions of the BC-breaking changes in MMDetection3D.
-
-## MMDetection3D 0.16.0
+## 0.16.0
 
 ### Returned values of `QueryAndGroup` operation
 
@@ -26,7 +22,7 @@ We adopt a new pre-processing procedure for the ScanNet dataset in order to supp
 
 Please refer to the ScanNet [README.md](https://github.com/open-mmlab/mmdetection3d/blob/master/data/scannet/README.md/) for more details.
 
-## MMDetection3D 0.15.0
+## 0.15.0
 
 ### MMCV Version
 
@@ -45,7 +41,7 @@ We modified the dataset augmentation function `BackgroundPointsFilter`([here](ht
 
 We enhance the pipeline function `IndoorPatchPointSample` used in point cloud segmentation task by adding more choices for patch selection. Also, we plan to remove the unused parameter `sample_rate` in the future. Please modify the code as well as the config files accordingly if you use this transform.
 
-## MMDetection3D 0.14.0
+## 0.14.0
 
 ### Dataset class for 3D segmentation task
 
@@ -65,7 +61,7 @@ We adopt new pre-processing and conversion steps of ScanNet dataset. In previous
 
 We have trained a [VoteNet](https://github.com/open-mmlab/mmdetection3d/blob/master/configs/votenet/votenet_8x8_scannet-3d-18class.py) model on the newly processed ScanNet dataset and get similar benchmark results. In order to prepare ScanNet data for both detection and segmentation tasks, please re-run the new pre-processing scripts following the ScanNet [README.md](https://github.com/open-mmlab/mmdetection3d/blob/master/data/scannet/README.md/).
 
-## MMDetection3D 0.12.0
+## 0.12.0
 
 ### SUNRGBD dataset for ImVoteNet
 
@@ -77,7 +73,7 @@ We adopt a new pre-processing procedure for the SUNRGBD dataset in order to supp
 
 Please refer to the SUNRGBD [README.md](https://github.com/open-mmlab/mmdetection3d/blob/master/data/sunrgbd/README.md/) for more details.
 
-## MMDetection3D 0.6.0
+## 0.6.0
 
 ### VoteNet model structure update
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -11,6 +11,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import pytorch_sphinx_theme
 import subprocess
 import sys
 from m2r import MdInclude
@@ -48,6 +49,7 @@ def get_version():
  'recommonmark',
  'sphinx_markdown_tables',
  'sphinx.ext.autosectionlabel',
+ 'sphinx_copybutton',
 ]
 
 autodoc_mock_imports = [
@@ -80,12 +82,103 @@ def get_version():
 # 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://mmocr.readthedocs.io/en/latest/',
+ 'menu': [
+ {
+ 'name': 'GitHub',
+ 'url': 'https://github.com/open-mmlab/mmdetection3d'
+ },
+ {
+ 'name':
+ 'Projects',
+ 'children': [
+ {
+ 'name': 'MMAction2',
+ 'url': 'https://github.com/open-mmlab/mmaction2',
+ },
+ {
+ 'name': 'MMClassification',
+ 'url': 'https://github.com/open-mmlab/mmclassification',
+ },
+ {
+ 'name': 'MMCV',
+ 'url': 'https://github.com/open-mmlab/mmmmcv',
+ },
+ {
+ 'name': 'MMDetection',
+ 'url': 'https://github.com/open-mmlab/mmdetection',
+ },
+ {
+ 'name': 'MMEditing',
+ 'url': 'https://github.com/open-mmlab/mmediting',
+ },
+ {
+ 'name': 'MMGeneration',
+ 'url': 'https://github.com/open-mmlab/mmgeneration',
+ },
+ {
+ 'name': 'MMOCR',
+ 'url': 'https://github.com/open-mmlab/mmocr',
+ },
+ {
+ 'name': 'MMPose',
+ 'url': 'https://github.com/open-mmlab/mmpose',
+ },
+ {
+ 'name': 'MMSegmentation',
+ 'url': 'https://github.com/open-mmlab/mmsegmentation',
+ },
+ {
+ 'name': 'MMTracking',
+ 'url': 'https://github.com/open-mmlab/mmtracking',
+ },
+ ]
+ },
+ {
+ 'name':
+ 'OpenMMLab',
+ 'children': [
+ {
+ 'name': 'Homepage',
+ 'url': 'https://openmmlab.com/'
+ },
+ {
+ 'name': 'GitHub',
+ 'url': 'https://github.com/open-mmlab/'
+ },
+ {
+ 'name': 'Twitter',
+ 'url': 'https://twitter.com/OpenMMLab'
+ },
+ {
+ 'name': 'Zhihu',
+ 'url': 'https://zhihu.com/people/openmmlab'
+ },
+ ]
+ },
+ ]
+}
 
 # 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']
+
+latex_documents = [
+ (master_doc, 'mmcv.tex', 'mmcv Documentation', 'MMCV Contributors',
+ 'manual'),
+]
+
+# -- Extension configuration -------------------------------------------------
+# Ignore >>> when copying code
+copybutton_prompt_text = r'>>> |\.\.\. '
+copybutton_prompt_is_regexp = True
 
 
 def builder_inited_handler(app):

diff --git a/docs/index.rst b/docs/index.rst
@@ -2,59 +2,91 @@ Welcome to MMDetection3D's documentation!
 ==========================================
 
 .. toctree::
- :maxdepth: 2
+ :maxdepth: 1
  :caption: Get Started
 
  getting_started.md
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Demo
+
  demo.md
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Model Zoo
+
  model_zoo.md
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Data Preparation
+
  data_preparation.md
 
 .. toctree::
- :maxdepth: 2
- :caption: Quick Run
+ :maxdepth: 1
+ :caption: Exist Data and Model
 
  1_exist_data_model.md
+
+.. toctree::
+ :maxdepth: 1
+ :caption: New Data and Model
+
  2_new_data_model.md
 
 .. toctree::
- :maxdepth: 2
+ :maxdepth: 1
  :caption: Supported Tasks
 
  supported_tasks/index.rst
 
 .. toctree::
- :maxdepth: 2
+ :maxdepth: 1
  :caption: Datasets
 
  datasets/index.rst
 
 .. toctree::
- :maxdepth: 2
+ :maxdepth: 1
  :caption: Tutorials
 
  tutorials/index.rst
 
 .. toctree::
- :maxdepth: 2
+ :maxdepth: 1
  :caption: Useful Tools and Scripts
 
  useful_tools.md
 
 .. toctree::
- :maxdepth: 2
+ :maxdepth: 1
  :caption: Notes
 
  benchmarks.md
+
+.. toctree::
+ :maxdepth: 1
+ :caption: FAQ
+
  faq.md
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Compatibility
+
  compatibility.md
 
 .. toctree::
+ :maxdepth: 1
  :caption: API Reference
 
  api.rst
 
 .. toctree::
+ :maxdepth: 1
  :caption: Switch Language
 
  switch_language.md

diff --git a/docs_zh-CN/1_exist_data_model.md b/docs_zh-CN/1_exist_data_model.md
@@ -1,4 +1,4 @@
-# 1：使用已有模型在标准数据集上进行推理和训练
+# 1: 使用已有模型在标准数据集上进行推理和训练
 
 ## 使用已有模型进行推理
 

diff --git a/docs_zh-CN/_static/css/readthedocs.css b/docs_zh-CN/_static/css/readthedocs.css
@@ -0,0 +1,6 @@
+.header-logo {
+ background-image: url("../image/mmdet3d-logo.png");
+ background-size: 182.5px 40px;
+ height: 40px;
+ width: 182.5px;
+}
diff --git a/docs_zh-CN/_static/image/mmdet3d-logo.png b/docs_zh-CN/_static/image/mmdet3d-logo.png
diff --git a/docs_zh-CN/api.rst b/docs_zh-CN/api.rst
@@ -1,6 +1,3 @@
-API Documentation
-=================
-
 mmdet3d.core
 --------------
 

diff --git a/docs_zh-CN/compatibility.md b/docs_zh-CN/compatibility.md
@@ -1 +1 @@
-# 和过去版本的 MMDetection3D 的兼容性
+## 0.16.0