[Docs] Update readthedocs (#2419)

* update docs build

* fix lint

* update

* update

docs/en/conf.py

+# Copyright (c) OpenMMLab. All rights reserved.
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
@@ -9,15 +10,12 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+
 import os
 import subprocess
 import sys
 
 import pytorch_sphinx_theme
-from m2r import MdInclude
-from recommonmark.transform import AutoStructify
-from sphinx.builders.html import StandaloneHTMLBuilder
 
 sys.path.insert(0, os.path.abspath('../../'))
 
@@ -27,17 +25,12 @@ project = 'MMDetection3D'
 copyright = '2020-2023, OpenMMLab'
 author = 'MMDetection3D Authors'
 
+# The full version, including alpha/beta/rc tags
 version_file = '../../mmdet3d/version.py'
-
-
-def get_version():
-    with open(version_file, 'r') as f:
+with open(version_file) as f:
     exec(compile(f.read(), version_file, 'exec'))
-    return locals()['__version__']
-
-
-# The full version, including alpha/beta/rc tags
-release = get_version()
+__version__ = locals()['__version__']
+release = __version__
 
 # -- General configuration ---------------------------------------------------
 
@@ -48,17 +41,24 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
-    'myst_parser',
     'sphinx_markdown_tables',
-    'sphinx.ext.autosectionlabel',
     'sphinx_copybutton',
+    'myst_parser',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc.typehints',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.autosectionlabel',
+    'sphinx_tabs.tabs',
 ]
+autodoc_typehints = 'description'
+autodoc_mock_imports = ['mmcv._ext']
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
 
-autodoc_mock_imports = [
-    'matplotlib', 'nuscenes', 'PIL', 'pycocotools', 'pyquaternion',
-    'terminaltables', 'mmdet3d.version', 'mmdet3d.ops', 'mmcv.ops'
-]
-autosectionlabel_prefix_document = True
+# Ignore >>> when copying code
+copybutton_prompt_text = r'>>> |\.\.\. '
+copybutton_prompt_is_regexp = True
+
+myst_enable_extensions = ['colon_fence']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -87,9 +87,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # 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',
@@ -99,6 +97,14 @@ html_theme_options = {
             'name':
             'Upstream',
             'children': [
+                {
+                    'name':
+                    'MMEngine',
+                    'url':
+                    'https://github.com/open-mmlab/mmengine',
+                    'description':
+                    'Foundational library for training deep learning models'
+                },
                 {
                     'name': 'MMCV',
                     'url': 'https://github.com/open-mmlab/mmcv',
@@ -125,22 +131,28 @@ master_doc = 'index'
 # 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'),
+html_css_files = [
+    'https://cdn.datatables.net/1.13.2/css/dataTables.bootstrap5.min.css',
+    'css/readthedocs.css'
 ]
-
-# set priority when building html
-StandaloneHTMLBuilder.supported_image_types = [
-    'image/svg+xml', 'image/gif', 'image/png', 'image/jpeg'
+html_js_files = [
+    'https://cdn.datatables.net/1.13.2/js/jquery.dataTables.min.js',
+    'https://cdn.datatables.net/1.13.2/js/dataTables.bootstrap5.min.js',
+    'js/collapsed.js',
+    'js/table.js',
 ]
-# Enable ::: for my_st
-myst_enable_extensions = ['colon_fence']
-myst_heading_anchors = 3
 
-language = 'en'
+myst_heading_anchors = 4
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable', None),
+    'torch': ('https://pytorch.org/docs/stable/', None),
+    'mmcv': ('https://mmcv.readthedocs.io/en/latest/', None),
+    'mmengine': ('https://mmengine.readthedocs.io/en/latest/', None),
+    'mmdetection': ('https://mmdetection.readthedocs.io/en/latest/', None),
+}
 
 
 def builder_inited_handler(app):
@@ -149,13 +161,3 @@ def builder_inited_handler(app):
 
 def setup(app):
     app.connect('builder-inited', builder_inited_handler)
-    app.add_config_value('no_underscore_emphasis', False, 'env')
-    app.add_config_value('m2r_parse_relative_links', False, 'env')
-    app.add_config_value('m2r_anonymous_references', False, 'env')
-    app.add_config_value('m2r_disable_inline_math', False, 'env')
-    app.add_directive('mdinclude', MdInclude)
-    app.add_config_value('recommonmark_config', {
-        'auto_toc_tree_section': 'Contents',
-        'enable_eval_rst': True,
-    }, True)
-    app.add_transform(AutoStructify)

docs/en/stat.py

@@ -6,28 +6,28 @@ from os import path as osp
 
 import numpy as np
 
-url_prefix = 'https://github.com/open-mmlab/mmdetection3d/blob/master/'
+url_prefix = 'https://github.com/open-mmlab/mmdetection3d/blob/main'
 
-files = sorted(glob.glob('../configs/*/README.md'))
+files = sorted(glob.glob('../../configs/*/README.md'))
 
 stats = []
 titles = []
 num_ckpts = 0
 
 for f in files:
-    url = osp.dirname(f.replace('../', url_prefix))
+    url = osp.dirname(f.replace('../../', url_prefix))
 
     with open(f, 'r') as content_file:
         content = content_file.read()
 
-    title = content.split('\n')[0].replace('#', '').strip()
+    title = content.split('\n')[0].replace('# ', '').strip()
     ckpts = set(x.lower().strip()
-                for x in re.findall(r'https?://download.*\.pth', content)
-                if 'mmdetection3d' in x)
+                for x in re.findall(r'\[model\]\((https?.*)\)', content))
+
     if len(ckpts) == 0:
         continue
 
-    _papertype = [x for x in re.findall(r'<!-- \[([A-Z]+)\] -->', content)]
+    _papertype = [x for x in re.findall(r'\[([A-Z]+)\]', content)]
     assert len(_papertype) > 0
     papertype = _papertype[0]
 
@@ -35,6 +35,7 @@ for f in files:
 
     titles.append(title)
     num_ckpts += len(ckpts)
+
     statsmsg = f"""
 \t* [{papertype}] [{title}]({url}) ({len(ckpts)} ckpts)
 """
@@ -49,14 +50,15 @@ countstr = '\n'.join(
     [f'   - {t}: {c}' for t, c in zip(papertypes, papercounts)])
 
 modelzoo = f"""
-\n## Model Zoo Statistics
+# Model Zoo Statistics
 
 * Number of papers: {len(set(titles))}
 {countstr}
 
 * Number of checkpoints: {num_ckpts}
+
 {msglist}
 """
 
-with open('model_zoo.md', 'a') as f:
+with open('modelzoo_statistics.md', 'w') as f:
     f.write(modelzoo)

docs/zh_cn/conf.py

+# Copyright (c) OpenMMLab. All rights reserved.
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
@@ -9,15 +10,12 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+
 import os
 import subprocess
 import sys
 
 import pytorch_sphinx_theme
-from m2r import MdInclude
-from recommonmark.transform import AutoStructify
-from sphinx.builders.html import StandaloneHTMLBuilder
 
 sys.path.insert(0, os.path.abspath('../../'))
 
@@ -27,17 +25,12 @@ project = 'MMDetection3D'
 copyright = '2020-2023, OpenMMLab'
 author = 'MMDetection3D Authors'
 
+# The full version, including alpha/beta/rc tags
 version_file = '../../mmdet3d/version.py'
-
-
-def get_version():
-    with open(version_file, 'r') as f:
+with open(version_file) as f:
     exec(compile(f.read(), version_file, 'exec'))
-    return locals()['__version__']
-
-
-# The full version, including alpha/beta/rc tags
-release = get_version()
+__version__ = locals()['__version__']
+release = __version__
 
 # -- General configuration ---------------------------------------------------
 
@@ -48,17 +41,24 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
-    'myst_parser',
     'sphinx_markdown_tables',
-    'sphinx.ext.autosectionlabel',
     'sphinx_copybutton',
+    'myst_parser',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc.typehints',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.autosectionlabel',
+    'sphinx_tabs.tabs',
 ]
+autodoc_typehints = 'description'
+autodoc_mock_imports = ['mmcv._ext']
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
 
-autodoc_mock_imports = [
-    'matplotlib', 'nuscenes', 'PIL', 'pycocotools', 'pyquaternion',
-    'terminaltables', 'mmdet3d.version', 'mmdet3d.ops', 'mmcv.ops'
-]
-autosectionlabel_prefix_document = True
+# Ignore >>> when copying code
+copybutton_prompt_text = r'>>> |\.\.\. '
+copybutton_prompt_is_regexp = True
+
+myst_enable_extensions = ['colon_fence']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -87,9 +87,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # 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',
@@ -99,6 +97,11 @@ html_theme_options = {
             'name':
             '上游库',
             'children': [
+                {
+                    'name': 'MMEngine',
+                    'url': 'https://github.com/open-mmlab/mmengine',
+                    'description': '深度学习模型训练基础库'
+                },
                 {
                     'name': 'MMCV',
                     'url': 'https://github.com/open-mmlab/mmcv',
@@ -114,10 +117,10 @@ html_theme_options = {
     ],
     # Specify the language of shared menu
     'menu_lang':
-    'cn',
+    'en'
 }
 
-language = 'zh_CN'
+language = 'en'
 
 master_doc = 'index'
 
@@ -125,22 +128,28 @@ master_doc = 'index'
 # 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'),
+html_css_files = [
+    'https://cdn.datatables.net/1.13.2/css/dataTables.bootstrap5.min.css',
+    'css/readthedocs.css'
 ]
-
-# set priority when building html
-StandaloneHTMLBuilder.supported_image_types = [
-    'image/svg+xml', 'image/gif', 'image/png', 'image/jpeg'
+html_js_files = [
+    'https://cdn.datatables.net/1.13.2/js/jquery.dataTables.min.js',
+    'https://cdn.datatables.net/1.13.2/js/dataTables.bootstrap5.min.js',
+    'js/collapsed.js',
+    'js/table.js',
 ]
-# Enable ::: for my_st
-myst_enable_extensions = ['colon_fence']
-myst_heading_anchors = 3
 
-language = 'zh_CN'
+myst_heading_anchors = 4
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable', None),
+    'torch': ('https://pytorch.org/docs/stable/', None),
+    'mmcv': ('https://mmcv.readthedocs.io/zh_CN/latest/', None),
+    'mmengine': ('https://mmengine.readthedocs.io/zh_CN/latest/', None),
+    'mmdetection': ('https://mmdetection.readthedocs.io/zh_CN/latest/', None),
+}
 
 
 def builder_inited_handler(app):
@@ -149,13 +158,3 @@ def builder_inited_handler(app):
 
 def setup(app):
     app.connect('builder-inited', builder_inited_handler)
-    app.add_config_value('no_underscore_emphasis', False, 'env')
-    app.add_config_value('m2r_parse_relative_links', False, 'env')
-    app.add_config_value('m2r_anonymous_references', False, 'env')
-    app.add_config_value('m2r_disable_inline_math', False, 'env')
-    app.add_directive('mdinclude', MdInclude)
-    app.add_config_value('recommonmark_config', {
-        'auto_toc_tree_section': 'Contents',
-        'enable_eval_rst': True,
-    }, True)
-    app.add_transform(AutoStructify)

docs/zh_cn/make.bat

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/zh_cn/stat.py

@@ -8,26 +8,26 @@ import numpy as np
 
 url_prefix = 'https://github.com/open-mmlab/mmdetection3d/blob/main/'
 
-files = sorted(glob.glob('../configs/*/README.md'))
+files = sorted(glob.glob('../../configs/*/README.md'))
 
 stats = []
 titles = []
 num_ckpts = 0
 
 for f in files:
-    url = osp.dirname(f.replace('../', url_prefix))
+    url = osp.dirname(f.replace('../../', url_prefix))
 
     with open(f, 'r') as content_file:
         content = content_file.read()
 
-    title = content.split('\n')[0].replace('#', '').strip()
+    title = content.split('\n')[0].replace('# ', '').strip()
     ckpts = set(x.lower().strip()
-                for x in re.findall(r'https?://download.*\.pth', content)
-                if 'mmdetection3d' in x)
+                for x in re.findall(r'\[model\]\((https?.*)\)', content))
+
     if len(ckpts) == 0:
         continue
 
-    _papertype = [x for x in re.findall(r'<!-- \[([A-Z]+)\] -->', content)]
+    _papertype = [x for x in re.findall(r'\[([A-Z]+)\]', content)]
     assert len(_papertype) > 0
     papertype = _papertype[0]
 
@@ -35,6 +35,7 @@ for f in files:
 
     titles.append(title)
     num_ckpts += len(ckpts)
+
     statsmsg = f"""
 \t* [{papertype}] [{title}]({url}) ({len(ckpts)} ckpts)
 """
@@ -49,14 +50,15 @@ countstr = '\n'.join(
     [f'   - {t}: {c}' for t, c in zip(papertypes, papercounts)])
 
 modelzoo = f"""
-\n## Model Zoo Statistics
+# Model Zoo Statistics
 
 * Number of papers: {len(set(titles))}
 {countstr}
 
 * Number of checkpoints: {num_ckpts}
+
 {msglist}
 """
 
-with open('model_zoo.md', 'a') as f:
+with open('modelzoo_statistics.md', 'w') as f:
     f.write(modelzoo)

requirements/docs.txt

 docutils==0.16.0
-m2r==0.2.1
-mistune==0.8.4
+markdown>=3.4.0
 myst-parser
 -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-tabs
+sphinx_copybutton
+sphinx_markdown_tables>=0.0.16
+tabulate