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.
#
# 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'
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
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 ---------------------------------------------------
......@@ -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
View file @ 47635c37
......@@ -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
View file @ 47635c37
# 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'
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
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 ---------------------------------------------------
......@@ -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 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
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
View file @ 47635c37
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
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