[Docs] Use PyTorch sphinx theme (#1321)

* [Docs] Use PyTorch sphinx theme

* add sphinx-copybutton

* add twitter and zhihu link

* remove shpinx_rtd_theme from doc.xtx

* update docs.txt

* update conf.py

docs/_static/css/readthedocs.css

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

docs/api.rst

@@ -1,7 +1,3 @@
-API Reference
-=================
-
-
 fileio
 -------
 .. automodule:: mmcv.fileio

docs/community.rst

@@ -1,8 +0,0 @@
-Community
-===========
-
-.. toctree::
-   :maxdepth: 2
-
-   community/contributing.md
-   community/pr.md

docs/compatibility.md

@@ -1,6 +1,4 @@
-## Compatibility of MMCV
-
-### MMCV v1.3.11
+### v1.3.11
 
 In order to flexibly support more backends and hardwares like `NVIDIA GPUs` and `AMD GPUs`, the directory of `mmcv/ops/csrc` is refactored. Note that this refactoring will not affect the usage in API. For related information, please refer to [PR1206](https://github.com/open-mmlab/mmcv/pull/1206).
 

docs/conf.py

@@ -14,6 +14,7 @@
 import os
 import sys
 
+import pytorch_sphinx_theme
 from m2r import MdInclude
 from recommonmark.transform import AutoStructify
 from sphinx.builders.html import StandaloneHTMLBuilder
@@ -53,6 +54,7 @@ extensions = [
     'sphinx.ext.autosectionlabel',
     'sphinx_markdown_tables',
     'myst_parser',
+    'sphinx_copybutton',
 ]  # yapf: disable
 
 autodoc_mock_imports = ['mmcv._ext', 'mmcv.utils.ext_loader', 'torchvision']
@@ -92,18 +94,97 @@ pygments_style = 'sphinx'
 # 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()]
 
 # 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 = {}
+html_theme_options = {
+    # 'logo_url': 'https://mmocr.readthedocs.io/en/latest/',
+    'menu': [
+        {
+            'name': 'GitHub',
+            'url': 'https://github.com/open-mmlab/mmcv'
+        },
+        {
+            'name':
+            'Projects',
+            'children': [
+                {
+                    'name': 'MMAction2',
+                    'url': 'https://github.com/open-mmlab/mmaction2',
+                },
+                {
+                    'name': 'MMClassification',
+                    'url': 'https://github.com/open-mmlab/mmclassification',
+                },
+                {
+                    'name': 'MMDetection',
+                    'url': 'https://github.com/open-mmlab/mmdetection',
+                },
+                {
+                    'name': 'MMDetection3D',
+                    'url': 'https://github.com/open-mmlab/mmdetection3d',
+                },
+                {
+                    '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']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -144,7 +225,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'mmcv.tex', 'mmcv Documentation', 'Kai Chen', 'manual'),
+    (master_doc, 'mmcv.tex', 'mmcv Documentation', 'MMCV Contributors',
+     'manual'),
 ]
 
 # -- Options for manual page output ------------------------------------------
@@ -185,6 +267,9 @@ StandaloneHTMLBuilder.supported_image_types = [
     'image/svg+xml', 'image/gif', 'image/png', 'image/jpeg'
 ]
 # -- Extension configuration -------------------------------------------------
+# Ignore >>> when copying code
+copybutton_prompt_text = r'>>> |\.\.\. '
+copybutton_prompt_is_regexp = True
 
 
 def setup(app):

docs/deployment.rst

@@ -1,11 +0,0 @@
-Deployment
-================
-
-.. toctree::
-    :maxdepth: 2
-
-    deployment/onnx.md
-    deployment/onnxruntime_op.md
-    deployment/onnxruntime_custom_ops.md
-    deployment/tensorrt_plugin.md
-    deployment/tensorrt_custom_ops.md

docs/get_started.rst

@@ -1,9 +0,0 @@
-Get started
-===================
-
-.. toctree::
-    :maxdepth: 2
-
-    get_started/introduction.md
-    get_started/installation.md
-    get_started/build.md

docs/get_started/installation.md

@@ -54,13 +54,13 @@ For more details, please refer the the following tables.
   <tbody>
     <tr>
       <th width="80"> CUDA </th>
-      <th valign="bottom" align="left" width="100">torch 1.9</th>
-      <th valign="bottom" align="left" width="100">torch 1.8</th>
-      <th valign="bottom" align="left" width="100">torch 1.7</th>
-      <th valign="bottom" align="left" width="100">torch 1.6</th>
-      <th valign="bottom" align="left" width="100">torch 1.5</th>
-      <th valign="bottom" align="left" width="100">torch 1.4</th>
-      <th valign="bottom" align="left" width="100">torch 1.3</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.9</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.8</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.7</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.6</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.5</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.4</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.3</th>
     </tr>
     <tr>
       <td align="left">11.1</td>

docs/get_started/introduction.md

@@ -1,9 +1,5 @@
 ## Introduction
 
-<div align="center">
-    <img src="https://raw.githubusercontent.com/open-mmlab/mmcv/master/docs/mmcv-logo.png" width="300"/>
-</div>
-
 MMCV is a foundational library for computer vision research and supports many
 research projects as below:
 

docs/index.rst

@@ -4,16 +4,61 @@ Welcome to MMCV's documentation!
 You can switch between Chinese and English documents in the lower-left corner of the layout.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :caption: Get Started
+
+   get_started/introduction.md
+   get_started/installation.md
+   get_started/build.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Understand MMCV
+
+   understand_mmcv/config.md
+   understand_mmcv/registry.md
+   understand_mmcv/runner.md
+   understand_mmcv/io.md
+   understand_mmcv/data_process.md
+   understand_mmcv/visualization.md
+   understand_mmcv/cnn.md
+   understand_mmcv/ops.md
+   understand_mmcv/utils.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Deployment
+
+   deployment/onnx.md
+   deployment/onnxruntime_op.md
+   deployment/onnxruntime_custom_ops.md
+   deployment/tensorrt_plugin.md
+   deployment/tensorrt_custom_ops.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Compatibility
 
-   get_started.rst
-   understand_mmcv.rst
-   deployment.rst
    compatibility.md
-   faq.md
-   community.rst
-   api.rst
 
+.. toctree::
+   :maxdepth: 1
+   :caption: FAQ
+
+   faq.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Community
+
+   community/contributing.md
+   community/pr.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API Reference
+
+   api.rst
 
 Indices and tables
 ==================

docs/understand_mmcv.rst

@@ -1,15 +0,0 @@
-Understand MMCV
-=================
-
-.. toctree::
-   :maxdepth: 2
-
-   understand_mmcv/config.md
-   understand_mmcv/registry.md
-   understand_mmcv/runner.md
-   understand_mmcv/io.md
-   understand_mmcv/data_process.md
-   understand_mmcv/visualization.md
-   understand_mmcv/cnn.md
-   understand_mmcv/ops.md
-   understand_mmcv/utils.md

docs_zh_CN/_static/css/readthedocs.css

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

docs_zh_CN/api.rst

@@ -1,7 +1,3 @@
-API 文档
-=========
-
-
 fileio
 -------
 .. automodule:: mmcv.fileio

docs_zh_CN/community.rst

@@ -1,8 +0,0 @@
-社区
-===========
-
-.. toctree::
-   :maxdepth: 2
-
-   community/contributing.md
-   community/pr.md

docs_zh_CN/compatibility.md

@@ -1,6 +1,4 @@
-## MMCV 兼容性说明
-
-### MMCV v1.3.11
+### v1.3.11
 
 为了灵活地支持更多的后端和硬件，例如 `NVIDIA GPUs` 、`AMD GPUs`，我们重构了 `mmcv/ops/csrc` 目录。注意，这次重构不会影响 API 的使用。更多相关信息，请参考 [PR1206](https://github.com/open-mmlab/mmcv/pull/1206)。
 

docs_zh_CN/conf.py

@@ -14,6 +14,7 @@
 import os
 import sys
 
+import pytorch_sphinx_theme
 from m2r import MdInclude
 from recommonmark.transform import AutoStructify
 from sphinx.builders.html import StandaloneHTMLBuilder
@@ -53,6 +54,7 @@ extensions = [
     'sphinx.ext.autosectionlabel',
     'sphinx_markdown_tables',
     'myst_parser',
+    'sphinx_copybutton',
 ]  # yapf: disable
 
 autodoc_mock_imports = ['mmcv._ext', 'mmcv.utils.ext_loader', 'torchvision']
@@ -92,18 +94,97 @@ pygments_style = 'sphinx'
 # 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()]
 
 # 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 = {}
+html_theme_options = {
+    # 'logo_url': 'https://mmocr.readthedocs.io/en/latest/',
+    'menu': [
+        {
+            'name': 'GitHub',
+            'url': 'https://github.com/open-mmlab/mmcv'
+        },
+        {
+            'name':
+            '算法库',
+            'children': [
+                {
+                    'name': 'MMAction2',
+                    'url': 'https://github.com/open-mmlab/mmaction2',
+                },
+                {
+                    'name': 'MMClassification',
+                    'url': 'https://github.com/open-mmlab/mmclassification',
+                },
+                {
+                    'name': 'MMDetection',
+                    'url': 'https://github.com/open-mmlab/mmdetection',
+                },
+                {
+                    'name': 'MMDetection3D',
+                    'url': 'https://github.com/open-mmlab/mmdetection3d',
+                },
+                {
+                    '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': '官网',
+                    'url': 'https://openmmlab.com/'
+                },
+                {
+                    'name': 'GitHub',
+                    'url': 'https://github.com/open-mmlab/'
+                },
+                {
+                    'name': '推特',
+                    'url': 'https://twitter.com/OpenMMLab'
+                },
+                {
+                    'name': '知乎',
+                    '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 = ['../docs/_static']
+html_static_path = ['_static']
+html_css_files = ['css/readthedocs.css']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -144,7 +225,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'mmcv.tex', 'mmcv Documentation', 'Kai Chen', 'manual'),
+    (master_doc, 'mmcv.tex', 'mmcv Documentation', 'MMCV Contributors',
+     'manual'),
 ]
 
 # -- Options for manual page output ------------------------------------------
@@ -185,6 +267,9 @@ StandaloneHTMLBuilder.supported_image_types = [
     'image/svg+xml', 'image/gif', 'image/png', 'image/jpeg'
 ]
 # -- Extension configuration -------------------------------------------------
+# Ignore >>> when copying code
+copybutton_prompt_text = r'>>> |\.\.\. '
+copybutton_prompt_is_regexp = True
 
 
 def setup(app):

docs_zh_CN/deployment.rst

@@ -1,11 +0,0 @@
-部署
-========
-
-.. toctree::
-    :maxdepth: 2
-
-    deployment/onnx.md
-    deployment/onnxruntime_op.md
-    deployment/onnxruntime_custom_ops.md
-    deployment/tensorrt_plugin.md
-    deployment/tensorrt_custom_ops.md

docs_zh_CN/get_started.rst

@@ -1,9 +0,0 @@
-介绍及安装
-===================
-
-.. toctree::
-    :maxdepth: 2
-
-    get_started/introduction.md
-    get_started/installation.md
-    get_started/build.md

docs_zh_CN/get_started/installation.md

@@ -50,13 +50,13 @@ pip install mmcv-full==1.3.9 -f https://download.openmmlab.com/mmcv/dist/cu111/t
   <tbody>
     <tr>
       <th width="80"> CUDA </th>
-      <th valign="bottom" align="left" width="100">torch 1.9</th>
-      <th valign="bottom" align="left" width="100">torch 1.8</th>
-      <th valign="bottom" align="left" width="100">torch 1.7</th>
-      <th valign="bottom" align="left" width="100">torch 1.6</th>
-      <th valign="bottom" align="left" width="100">torch 1.5</th>
-      <th valign="bottom" align="left" width="100">torch 1.4</th>
-      <th valign="bottom" align="left" width="100">torch 1.3</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.9</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.8</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.7</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.6</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.5</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.4</th>
+      <th valign="bottom" align="left" style="min-width: 100px">torch 1.3</th>
     </tr>
     <tr>
       <td align="left">11.1</td>

docs_zh_CN/get_started/introduction.md

@@ -1,9 +1,5 @@
 ## 介绍 MMCV
 
-<div align="center">
-    <img src="https://raw.githubusercontent.com/open-mmlab/mmcv/master/docs/mmcv-logo.png" width="300"/>
-</div>
-
 MMCV 是一个面向计算机视觉的基础库，它支持了很多开源项目，例如：
 
 - [MMClassification](https://github.com/open-mmlab/mmclassification): OpenMMLab 图像分类工具箱

docs_zh_CN/index.rst

@@ -4,14 +4,60 @@
 您可以在页面左下角切换中英文文档。
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :caption: 介绍与安装
+
+   get_started/introduction.md
+   get_started/installation.md
+   get_started/build.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 深入理解 MMCV
+
+   understand_mmcv/config.md
+   understand_mmcv/registry.md
+   understand_mmcv/runner.md
+   understand_mmcv/io.md
+   understand_mmcv/data_process.md
+   understand_mmcv/visualization.md
+   understand_mmcv/cnn.md
+   understand_mmcv/ops.md
+   understand_mmcv/utils.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 部署
+
+   deployment/onnx.md
+   deployment/onnxruntime_op.md
+   deployment/onnxruntime_custom_ops.md
+   deployment/tensorrt_plugin.md
+   deployment/tensorrt_custom_ops.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 兼容性
 
-   get_started.rst
-   understand_mmcv.rst
-   deployment.rst
    compatibility.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 常见问题
+
    faq.md
-   community.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 社区
+
+   community/contributing.md
+   community/pr.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API 文档
+
    api.rst
 
 

docs_zh_CN/understand_mmcv.rst

@@ -1,15 +0,0 @@
-深入理解 MMCV
-=================
-
-.. toctree::
-   :maxdepth: 2
-
-   understand_mmcv/config.md
-   understand_mmcv/registry.md
-   understand_mmcv/runner.md
-   understand_mmcv/io.md
-   understand_mmcv/data_process.md
-   understand_mmcv/visualization.md
-   understand_mmcv/cnn.md
-   understand_mmcv/ops.md
-   understand_mmcv/utils.md

requirements/docs.txt

@@ -2,7 +2,8 @@ docutils==0.16.0
 m2r
 myst-parser
 opencv-python
+-e git+https://github.com/open-mmlab/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
 sphinx==4.0.2
+sphinx-copybutton
 sphinx_markdown_tables
-sphinx_rtd_theme==0.5.2
 torch

setup.cfg

@@ -14,6 +14,6 @@ line_length = 79
 multi_line_output = 0
 known_standard_library = pkg_resources,setuptools,logging,os,warnings,abc
 known_first_party = mmcv
-known_third_party = addict,cv2,m2r,numpy,onnx,onnxruntime,packaging,pytest,recommonmark,scipy,sphinx,tensorrt,torch,torchvision,yaml,yapf
+known_third_party = addict,cv2,m2r,numpy,onnx,onnxruntime,packaging,pytest,pytorch_sphinx_theme,recommonmark,scipy,sphinx,tensorrt,torch,torchvision,yaml,yapf
 no_lines_before = STDLIB,LOCALFOLDER
 default_section = THIRDPARTY