Skip to content

GitLab

Unverified Commit 47635c37 authored by Xiang Xu's avatar Xiang Xu Committed by GitHub
Browse files

[Docs] Update readthedocs (#2419) 

* update docs build

* fix lint

* update

* update
parent 5ea7fa1b
Hide whitespace changes
Inline Side-by-side
Showing with 154 additions and 113 deletions
docs/en/conf.py
View file @ 47635c37
# Copyright (c) OpenMMLab. All rights reserved.
# Configuration file for the Sphinx documentation builder. # Configuration file for the Sphinx documentation builder.
# #
# This file only contains a selection of the most common options. For a full # This file only contains a selection of the most common options. For a full
...@@ -9,15 +10,12 @@ ...@@ -9,15 +10,12 @@
# If extensions (or modules to document with autodoc) are in another directory, # 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 # 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. # documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os import os
import subprocess import subprocess
import sys import sys
import pytorch_sphinx_theme 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('../../')) sys.path.insert(0, os.path.abspath('../../'))
...@@ -27,17 +25,12 @@ project = 'MMDetection3D' ...@@ -27,17 +25,12 @@ project = 'MMDetection3D'
copyright = '2020-2023, OpenMMLab' copyright = '2020-2023, OpenMMLab'
author = 'MMDetection3D Authors' author = 'MMDetection3D Authors'
version_file = '../../mmdet3d/version.py'
def get_version():
with open(version_file, 'r') as f:
exec(compile(f.read(), version_file, 'exec'))
return locals()['__version__']
# The full version, including alpha/beta/rc tags # The full version, including alpha/beta/rc tags
release = get_version() version_file = '../../mmdet3d/version.py'
with open(version_file) as f:
exec(compile(f.read(), version_file, 'exec'))
__version__ = locals()['__version__']
release = __version__
# -- General configuration --------------------------------------------------- # -- General configuration ---------------------------------------------------
...@@ -48,17 +41,24 @@ extensions = [ ...@@ -48,17 +41,24 @@ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx.ext.napoleon', 'sphinx.ext.napoleon',
'sphinx.ext.viewcode', 'sphinx.ext.viewcode',
'myst_parser',
'sphinx_markdown_tables', 'sphinx_markdown_tables',
'sphinx.ext.autosectionlabel',
'sphinx_copybutton', '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 = [ # Ignore >>> when copying code
'matplotlib', 'nuscenes', 'PIL', 'pycocotools', 'pyquaternion', copybutton_prompt_text = r'>>> |\.\.\. '
'terminaltables', 'mmdet3d.version', 'mmdet3d.ops', 'mmcv.ops' copybutton_prompt_is_regexp = True
]
autosectionlabel_prefix_document = True myst_enable_extensions = ['colon_fence']
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
...@@ -87,9 +87,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] ...@@ -87,9 +87,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# html_theme = 'sphinx_rtd_theme' # html_theme = 'sphinx_rtd_theme'
html_theme = 'pytorch_sphinx_theme' html_theme = 'pytorch_sphinx_theme'
html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()] html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()]
html_theme_options = { html_theme_options = {
# 'logo_url': 'https://mmocr.readthedocs.io/en/latest/',
'menu': [ 'menu': [
{ {
'name': 'GitHub', 'name': 'GitHub',
...@@ -99,6 +97,14 @@ html_theme_options = { ...@@ -99,6 +97,14 @@ html_theme_options = {
'name': 'name':
'Upstream', 'Upstream',
'children': [ 'children': [
{
'name':
'MMEngine',
'url':
'https://github.com/open-mmlab/mmengine',
'description':
'Foundational library for training deep learning models'
},
{ {
'name': 'MMCV', 'name': 'MMCV',
'url': 'https://github.com/open-mmlab/mmcv', 'url': 'https://github.com/open-mmlab/mmcv',
...@@ -125,22 +131,28 @@ master_doc = 'index' ...@@ -125,22 +131,28 @@ master_doc = 'index'
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static'] html_static_path = ['_static']
html_css_files = ['css/readthedocs.css']
latex_documents = [ html_css_files = [
(master_doc, 'mmcv.tex', 'mmcv Documentation', 'MMCV Contributors', 'https://cdn.datatables.net/1.13.2/css/dataTables.bootstrap5.min.css',
'manual'), 'css/readthedocs.css'
] ]
html_js_files = [
# set priority when building html 'https://cdn.datatables.net/1.13.2/js/jquery.dataTables.min.js',
StandaloneHTMLBuilder.supported_image_types = [ 'https://cdn.datatables.net/1.13.2/js/dataTables.bootstrap5.min.js',
'image/svg+xml', 'image/gif', 'image/png', 'image/jpeg' '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): def builder_inited_handler(app):
...@@ -149,13 +161,3 @@ def builder_inited_handler(app): ...@@ -149,13 +161,3 @@ def builder_inited_handler(app):
def setup(app): def setup(app):
app.connect('builder-inited', builder_inited_handler) 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
View file @ 47635c37
...@@ -6,28 +6,28 @@ from os import path as osp ...@@ -6,28 +6,28 @@ from os import path as osp
import numpy as np 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 = [] stats = []
titles = [] titles = []
num_ckpts = 0 num_ckpts = 0
for f in files: 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: with open(f, 'r') as content_file:
content = content_file.read() content = content_file.read()
title = content.split('\n')[0].replace('#', '').strip() title = content.split('\n')[0].replace('# ', '').strip()
ckpts = set(x.lower().strip() ckpts = set(x.lower().strip()
for x in re.findall(r'https?://download.*\.pth', content) for x in re.findall(r'\[model\]\((https?.*)\)', content))
if 'mmdetection3d' in x)
if len(ckpts) == 0: if len(ckpts) == 0:
continue 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 assert len(_papertype) > 0
papertype = _papertype[0] papertype = _papertype[0]
...@@ -35,6 +35,7 @@ for f in files: ...@@ -35,6 +35,7 @@ for f in files:
titles.append(title) titles.append(title)
num_ckpts += len(ckpts) num_ckpts += len(ckpts)
statsmsg = f""" statsmsg = f"""
\t* [{papertype}] [{title}]({url}) ({len(ckpts)} ckpts) \t* [{papertype}] [{title}]({url}) ({len(ckpts)} ckpts)
""" """
...@@ -49,14 +50,15 @@ countstr = '\n'.join( ...@@ -49,14 +50,15 @@ countstr = '\n'.join(
[f' - {t}: {c}' for t, c in zip(papertypes, papercounts)]) [f' - {t}: {c}' for t, c in zip(papertypes, papercounts)])
modelzoo = f""" modelzoo = f"""
\n## Model Zoo Statistics # Model Zoo Statistics
* Number of papers: {len(set(titles))} * Number of papers: {len(set(titles))}
{countstr} {countstr}
* Number of checkpoints: {num_ckpts} * Number of checkpoints: {num_ckpts}
{msglist} {msglist}
""" """
with open('model_zoo.md', 'a') as f: with open('modelzoo_statistics.md', 'w') as f:
f.write(modelzoo) f.write(modelzoo)
docs/zh_cn/conf.py
View file @ 47635c37
# Copyright (c) OpenMMLab. All rights reserved.
# Configuration file for the Sphinx documentation builder. # Configuration file for the Sphinx documentation builder.
# #
# This file only contains a selection of the most common options. For a full # This file only contains a selection of the most common options. For a full
...@@ -9,15 +10,12 @@ ...@@ -9,15 +10,12 @@
# If extensions (or modules to document with autodoc) are in another directory, # 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 # 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. # documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os import os
import subprocess import subprocess
import sys import sys
import pytorch_sphinx_theme 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('../../')) sys.path.insert(0, os.path.abspath('../../'))
...@@ -27,17 +25,12 @@ project = 'MMDetection3D' ...@@ -27,17 +25,12 @@ project = 'MMDetection3D'
copyright = '2020-2023, OpenMMLab' copyright = '2020-2023, OpenMMLab'
author = 'MMDetection3D Authors' author = 'MMDetection3D Authors'
version_file = '../../mmdet3d/version.py'
def get_version():
with open(version_file, 'r') as f:
exec(compile(f.read(), version_file, 'exec'))
return locals()['__version__']
# The full version, including alpha/beta/rc tags # The full version, including alpha/beta/rc tags
release = get_version() version_file = '../../mmdet3d/version.py'
with open(version_file) as f:
exec(compile(f.read(), version_file, 'exec'))
__version__ = locals()['__version__']
release = __version__
# -- General configuration --------------------------------------------------- # -- General configuration ---------------------------------------------------
...@@ -48,17 +41,24 @@ extensions = [ ...@@ -48,17 +41,24 @@ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx.ext.napoleon', 'sphinx.ext.napoleon',
'sphinx.ext.viewcode', 'sphinx.ext.viewcode',
'myst_parser',
'sphinx_markdown_tables', 'sphinx_markdown_tables',
'sphinx.ext.autosectionlabel',
'sphinx_copybutton', '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 = [ # Ignore >>> when copying code
'matplotlib', 'nuscenes', 'PIL', 'pycocotools', 'pyquaternion', copybutton_prompt_text = r'>>> |\.\.\. '
'terminaltables', 'mmdet3d.version', 'mmdet3d.ops', 'mmcv.ops' copybutton_prompt_is_regexp = True
]
autosectionlabel_prefix_document = True myst_enable_extensions = ['colon_fence']
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
...@@ -87,9 +87,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] ...@@ -87,9 +87,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# html_theme = 'sphinx_rtd_theme' # html_theme = 'sphinx_rtd_theme'
html_theme = 'pytorch_sphinx_theme' html_theme = 'pytorch_sphinx_theme'
html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()] html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()]
html_theme_options = { html_theme_options = {
# 'logo_url': 'https://mmocr.readthedocs.io/en/latest/',
'menu': [ 'menu': [
{ {
'name': 'GitHub', 'name': 'GitHub',
...@@ -99,6 +97,11 @@ html_theme_options = { ...@@ -99,6 +97,11 @@ html_theme_options = {
'name': 'name':
'上游库', '上游库',
'children': [ 'children': [
{
'name': 'MMEngine',
'url': 'https://github.com/open-mmlab/mmengine',
'description': '深度学习模型训练基础库'
},
{ {
'name': 'MMCV', 'name': 'MMCV',
'url': 'https://github.com/open-mmlab/mmcv', 'url': 'https://github.com/open-mmlab/mmcv',
...@@ -114,10 +117,10 @@ html_theme_options = { ...@@ -114,10 +117,10 @@ html_theme_options = {
], ],
# Specify the language of shared menu # Specify the language of shared menu
'menu_lang': 'menu_lang':
'cn', 'en'
} }
language = 'zh_CN' language = 'en'
master_doc = 'index' master_doc = 'index'
...@@ -125,22 +128,28 @@ master_doc = 'index' ...@@ -125,22 +128,28 @@ master_doc = 'index'
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static'] html_static_path = ['_static']
html_css_files = ['css/readthedocs.css']
latex_documents = [ html_css_files = [
(master_doc, 'mmcv.tex', 'mmcv Documentation', 'MMCV Contributors', 'https://cdn.datatables.net/1.13.2/css/dataTables.bootstrap5.min.css',
'manual'), 'css/readthedocs.css'
] ]
html_js_files = [
# set priority when building html 'https://cdn.datatables.net/1.13.2/js/jquery.dataTables.min.js',
StandaloneHTMLBuilder.supported_image_types = [ 'https://cdn.datatables.net/1.13.2/js/dataTables.bootstrap5.min.js',
'image/svg+xml', 'image/gif', 'image/png', 'image/jpeg' '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): def builder_inited_handler(app):
...@@ -149,13 +158,3 @@ def builder_inited_handler(app): ...@@ -149,13 +158,3 @@ def builder_inited_handler(app):
def setup(app): def setup(app):
app.connect('builder-inited', builder_inited_handler) 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 0 → 100644
View file @ 47635c37
@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
View file @ 47635c37
...@@ -8,26 +8,26 @@ import numpy as np ...@@ -8,26 +8,26 @@ import numpy as np
url_prefix = 'https://github.com/open-mmlab/mmdetection3d/blob/main/' 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 = [] stats = []
titles = [] titles = []
num_ckpts = 0 num_ckpts = 0
for f in files: 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: with open(f, 'r') as content_file:
content = content_file.read() content = content_file.read()
title = content.split('\n')[0].replace('#', '').strip() title = content.split('\n')[0].replace('# ', '').strip()
ckpts = set(x.lower().strip() ckpts = set(x.lower().strip()
for x in re.findall(r'https?://download.*\.pth', content) for x in re.findall(r'\[model\]\((https?.*)\)', content))
if 'mmdetection3d' in x)
if len(ckpts) == 0: if len(ckpts) == 0:
continue 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 assert len(_papertype) > 0
papertype = _papertype[0] papertype = _papertype[0]
...@@ -35,6 +35,7 @@ for f in files: ...@@ -35,6 +35,7 @@ for f in files:
titles.append(title) titles.append(title)
num_ckpts += len(ckpts) num_ckpts += len(ckpts)
statsmsg = f""" statsmsg = f"""
\t* [{papertype}] [{title}]({url}) ({len(ckpts)} ckpts) \t* [{papertype}] [{title}]({url}) ({len(ckpts)} ckpts)
""" """
...@@ -49,14 +50,15 @@ countstr = '\n'.join( ...@@ -49,14 +50,15 @@ countstr = '\n'.join(
[f' - {t}: {c}' for t, c in zip(papertypes, papercounts)]) [f' - {t}: {c}' for t, c in zip(papertypes, papercounts)])
modelzoo = f""" modelzoo = f"""
\n## Model Zoo Statistics # Model Zoo Statistics
* Number of papers: {len(set(titles))} * Number of papers: {len(set(titles))}
{countstr} {countstr}
* Number of checkpoints: {num_ckpts} * Number of checkpoints: {num_ckpts}
{msglist} {msglist}
""" """
with open('model_zoo.md', 'a') as f: with open('modelzoo_statistics.md', 'w') as f:
f.write(modelzoo) f.write(modelzoo)
requirements/docs.txt
View file @ 47635c37
docutils==0.16.0 docutils==0.16.0
m2r==0.2.1 markdown>=3.4.0
mistune==0.8.4
myst-parser myst-parser
-e git+https://github.com/open-mmlab/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme -e git+https://github.com/open-mmlab/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
sphinx==4.0.2 sphinx==4.0.2
sphinx-copybutton sphinx-tabs
sphinx_markdown_tables sphinx_copybutton
sphinx_markdown_tables>=0.0.16
tabulate
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment