[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
open-mmlab · Sep 14, 2021 · 1216e5f · 1216e5f
1 parent 6434d0d
commit 1216e5f
Show file tree

Hide file tree

Showing 26 changed files with 310 additions and 142 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/mmcv-logo.png");
+    background-size: 85px 40px;
+    height: 40px;
+    width: 85px;
+}
diff --git a/docs/_static/image/mmcv-logo.png b/docs/_static/image/mmcv-logo.png
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,7 +1,3 @@
-API Reference
-=================
-
-
 fileio
 -------
 .. automodule:: mmcv.fileio

diff --git a/docs/community.rst b/docs/community.rst
diff --git a/docs/compatibility.md b/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).
 

diff --git a/docs/conf.py b/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 @@
     '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 @@
 # 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 @@
 # (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 @@
     '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):

diff --git a/docs/deployment.rst b/docs/deployment.rst
diff --git a/docs/get_started.rst b/docs/get_started.rst
diff --git a/docs/get_started/installation.md b/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>

diff --git a/docs/get_started/introduction.md b/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:
 

diff --git a/docs/index.rst b/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
+
+.. toctree::
+   :maxdepth: 1
+   :caption: FAQ
+
    faq.md
-   community.rst
-   api.rst
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Community
+
+   community/contributing.md
+   community/pr.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API Reference
+
+   api.rst
 
 Indices and tables
 ==================

diff --git a/docs/understand_mmcv.rst b/docs/understand_mmcv.rst
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/mmcv-logo.png");
+    background-size: 85px 40px;
+    height: 40px;
+    width: 85px;
+}
diff --git a/docs_zh_CN/_static/image/mmcv-logo.png b/docs_zh_CN/_static/image/mmcv-logo.png
diff --git a/docs_zh_CN/api.rst b/docs_zh_CN/api.rst
@@ -1,7 +1,3 @@
-API 文档
-=========
-
-
 fileio
 -------
 .. automodule:: mmcv.fileio

diff --git a/docs_zh_CN/community.rst b/docs_zh_CN/community.rst
diff --git a/docs_zh_CN/compatibility.md b/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)。