From 1d9a33e16ea05f6afee15165d3e08bf8f803647b Mon Sep 17 00:00:00 2001 From: sibo2rr <1415419833@qq.com> Date: Wed, 15 Dec 2021 16:04:23 +0800 Subject: [PATCH] add read the doc --- docs/zh_CN/Makefile | 20 +++ docs/zh_CN/advanced_tutorials/index.rst | 11 ++ .../DataAugmentation.md | 1 - .../image_classification.md | 2 +- docs/zh_CN/algorithm_introduction/index.rst | 12 ++ docs/zh_CN/conf.py | 66 +++++++ docs/zh_CN/data_preparation/index.rst | 8 + docs/zh_CN/faq_series/index.rst | 10 ++ .../image_recognition_pipeline/index.rst | 9 + docs/zh_CN/index.rst | 18 ++ docs/zh_CN/inference_deployment/index.rst | 14 ++ docs/zh_CN/installation/index.rst | 8 + docs/zh_CN/introduction/index.rst | 8 + docs/zh_CN/make.bat | 35 ++++ docs/zh_CN/models/index.rst | 30 +++- docs/zh_CN/models_training/index.rst | 10 ++ docs/zh_CN/others/index.rst | 16 ++ docs/zh_CN/quick_start/index.rst | 10 ++ docs/zh_CN/readFile.py | 65 +++++++ "readthedoc\346\214\207\345\215\227.md" | 161 ++++++++++++++++++ 20 files changed, 504 insertions(+), 10 deletions(-) create mode 100644 docs/zh_CN/Makefile create mode 100644 docs/zh_CN/advanced_tutorials/index.rst create mode 100644 docs/zh_CN/algorithm_introduction/index.rst create mode 100644 docs/zh_CN/conf.py create mode 100644 docs/zh_CN/data_preparation/index.rst create mode 100644 docs/zh_CN/faq_series/index.rst create mode 100644 docs/zh_CN/image_recognition_pipeline/index.rst create mode 100644 docs/zh_CN/index.rst create mode 100644 docs/zh_CN/inference_deployment/index.rst create mode 100644 docs/zh_CN/installation/index.rst create mode 100644 docs/zh_CN/introduction/index.rst create mode 100644 docs/zh_CN/make.bat create mode 100644 docs/zh_CN/models_training/index.rst create mode 100644 docs/zh_CN/others/index.rst create mode 100644 docs/zh_CN/quick_start/index.rst create mode 100644 docs/zh_CN/readFile.py create mode 100644 "readthedoc\346\214\207\345\215\227.md" diff --git a/docs/zh_CN/Makefile b/docs/zh_CN/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/zh_CN/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/zh_CN/advanced_tutorials/index.rst b/docs/zh_CN/advanced_tutorials/index.rst new file mode 100644 index 00000000..7cb53030 --- /dev/null +++ b/docs/zh_CN/advanced_tutorials/index.rst @@ -0,0 +1,11 @@ +高级教程 +================================ + +.. toctree:: + :maxdepth: 2 + + model_prune_quantization.md + knowledge_distillation.md + how_to_contribute.md + code_overview.md + DataAugmentation.md diff --git a/docs/zh_CN/algorithm_introduction/DataAugmentation.md b/docs/zh_CN/algorithm_introduction/DataAugmentation.md index dbc34698..3b14de81 100644 --- a/docs/zh_CN/algorithm_introduction/DataAugmentation.md +++ b/docs/zh_CN/algorithm_introduction/DataAugmentation.md @@ -1,6 +1,5 @@ # 数据增强 ------ - ## 目录 - [1. 数据增强简介](#1) diff --git a/docs/zh_CN/algorithm_introduction/image_classification.md b/docs/zh_CN/algorithm_introduction/image_classification.md index a7454c2d..3624199c 100644 --- a/docs/zh_CN/algorithm_introduction/image_classification.md +++ b/docs/zh_CN/algorithm_introduction/image_classification.md @@ -1,5 +1,5 @@ +# Image Classification ------- ## 目录 diff --git a/docs/zh_CN/algorithm_introduction/index.rst b/docs/zh_CN/algorithm_introduction/index.rst new file mode 100644 index 00000000..586193a1 --- /dev/null +++ b/docs/zh_CN/algorithm_introduction/index.rst @@ -0,0 +1,12 @@ +算法介绍 +================================ + +.. toctree:: + :maxdepth: 2 + + model_prune_quantization.md + ImageNet_models.md + metric_learning.md + knowledge_distillation.md + image_classification.md + DataAugmentation.md diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py new file mode 100644 index 00000000..9e4967d6 --- /dev/null +++ b/docs/zh_CN/conf.py @@ -0,0 +1,66 @@ +# Configuration file for the Sphinx documentation builder. +from recommonmark.parser import CommonMarkParser +import sphinx_rtd_theme +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# 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 sys +# sys.path.insert(0, os.path.abspath('.')) +extensions = ['recommonmark'] + +# -- Project information ----------------------------------------------------- + +project = 'paddleclas' +copyright = '2021, paddleclas' +author = 'paddleclas' + +# The full version, including alpha/beta/rc tags +release = '2.3' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['recommonmark'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'zh_CN' +source_parsers = { + '.md': CommonMarkParser, +} +source_suffix = ['.rst', '.md'] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# 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'] diff --git a/docs/zh_CN/data_preparation/index.rst b/docs/zh_CN/data_preparation/index.rst new file mode 100644 index 00000000..c851ca5f --- /dev/null +++ b/docs/zh_CN/data_preparation/index.rst @@ -0,0 +1,8 @@ +数据准备 +================================ + +.. toctree:: + :maxdepth: 2 + + recognition_dataset.md + classification_dataset.md diff --git a/docs/zh_CN/faq_series/index.rst b/docs/zh_CN/faq_series/index.rst new file mode 100644 index 00000000..f65427df --- /dev/null +++ b/docs/zh_CN/faq_series/index.rst @@ -0,0 +1,10 @@ +FAQ系列 +================================ + +.. toctree:: + :maxdepth: 2 + + faq_2021_s2.md + faq_2021_s1.md + faq_selected_30.md + faq_2020_s1.md diff --git a/docs/zh_CN/image_recognition_pipeline/index.rst b/docs/zh_CN/image_recognition_pipeline/index.rst new file mode 100644 index 00000000..3931a420 --- /dev/null +++ b/docs/zh_CN/image_recognition_pipeline/index.rst @@ -0,0 +1,9 @@ +图像识别流程 +================================ + +.. toctree:: + :maxdepth: 2 + + vector_search.md + mainbody_detection.md + feature_extraction.md diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst new file mode 100644 index 00000000..a8f715b8 --- /dev/null +++ b/docs/zh_CN/index.rst @@ -0,0 +1,18 @@ +欢迎使用PaddleClas图像分类库！ +================================ + +.. toctree:: + :maxdepth: 1 + + models_training/index + introduction/index + image_recognition_pipeline/index + others/index + faq_series/index + data_preparation/index + installation/index + models/index + advanced_tutorials/index + algorithm_introduction/index + inference_deployment/index + quick_start/index diff --git a/docs/zh_CN/inference_deployment/index.rst b/docs/zh_CN/inference_deployment/index.rst new file mode 100644 index 00000000..0148ad16 --- /dev/null +++ b/docs/zh_CN/inference_deployment/index.rst @@ -0,0 +1,14 @@ +推理部署 +================================ + +.. toctree:: + :maxdepth: 2 + + paddle_serving_deploy.md + whl_deploy.md + cpp_deploy_on_windows.md + python_deploy.md + paddle_hub_serving_deploy.md + cpp_deploy.md + paddle_lite_deploy.md + export_model.md diff --git a/docs/zh_CN/installation/index.rst b/docs/zh_CN/installation/index.rst new file mode 100644 index 00000000..752d0500 --- /dev/null +++ b/docs/zh_CN/installation/index.rst @@ -0,0 +1,8 @@ +安装 +================================ + +.. toctree:: + :maxdepth: 2 + + install_paddle.md + install_paddleclas.md diff --git a/docs/zh_CN/introduction/index.rst b/docs/zh_CN/introduction/index.rst new file mode 100644 index 00000000..b32dd358 --- /dev/null +++ b/docs/zh_CN/introduction/index.rst @@ -0,0 +1,8 @@ +介绍 +================================ + +.. toctree:: + :maxdepth: 2 + + function_intro.md + more_demo.md diff --git a/docs/zh_CN/make.bat b/docs/zh_CN/make.bat new file mode 100644 index 00000000..153be5e2 --- /dev/null +++ b/docs/zh_CN/make.bat @@ -0,0 +1,35 @@ +@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.https://www.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 diff --git a/docs/zh_CN/models/index.rst b/docs/zh_CN/models/index.rst index 1a64eb2b..223d4e50 100644 --- a/docs/zh_CN/models/index.rst +++ b/docs/zh_CN/models/index.rst @@ -2,15 +2,29 @@ ================================ .. toctree:: - :maxdepth: 1 - + :maxdepth: 2 + + DPN_DenseNet.md models_intro.md + RepVGG.md + EfficientNet_and_ResNeXt101_wsl.md + ViT_and_DeiT.md + SwinTransformer.md Tricks.md - ResNet_and_vd.md - Mobile.md + Others.md SEResNext_and_Res2Net.md - Inception.md + ESNet.md HRNet.md - DPN_DenseNet.md - EfficientNet_and_ResNeXt101_wsl.md - Others.md + ReXNet.md + Inception.md + TNT.md + RedNet.md + DLA.md + ResNeSt_RegNet.md + PP-LCNet.md + HarDNet.md + ResNet_and_vd.md + LeViT.md + Mobile.md + MixNet.md + Twins.md diff --git a/docs/zh_CN/models_training/index.rst b/docs/zh_CN/models_training/index.rst new file mode 100644 index 00000000..704ff4e2 --- /dev/null +++ b/docs/zh_CN/models_training/index.rst @@ -0,0 +1,10 @@ +模型训练 +================================ + +.. toctree:: + :maxdepth: 2 + + config_description.md + train_strategy.md + classification.md + recognition.md diff --git a/docs/zh_CN/others/index.rst b/docs/zh_CN/others/index.rst new file mode 100644 index 00000000..593b3ac6 --- /dev/null +++ b/docs/zh_CN/others/index.rst @@ -0,0 +1,16 @@ +其他 +================================ + +.. toctree:: + :maxdepth: 2 + + competition_support.md + paddle_mobile_inference.md + feature_visiualization.md + VisualDL.md + versions.md + update_history.md + more_demo.md + train_on_xpu.md + transfer_learning.md + train_with_DALI.md diff --git a/docs/zh_CN/quick_start/index.rst b/docs/zh_CN/quick_start/index.rst new file mode 100644 index 00000000..50af4716 --- /dev/null +++ b/docs/zh_CN/quick_start/index.rst @@ -0,0 +1,10 @@ +快速开始 +================================ + +.. toctree:: + :maxdepth: 2 + + quick_start_classification_new_user.md + quick_start_classification_professional.md + quick_start_recognition.md + quick_start_multilabel_classification.md diff --git a/docs/zh_CN/readFile.py b/docs/zh_CN/readFile.py new file mode 100644 index 00000000..a1a95ce9 --- /dev/null +++ b/docs/zh_CN/readFile.py @@ -0,0 +1,65 @@ +import os + +def file_name(file_dir): + temp = [] + for root, dirs, files in os.walk(file_dir): + print(dirs) #当前路径下所有子目录 + temp = dirs #存储需要的子目录 + break + + # 删除不需要的子目录 + temp.remove('images') + temp.remove('_templates') + temp.remove('_build') + temp.remove('_static') + chinese_name = ['模型训练', '介绍', '图像识别流程', '其他', 'FAQ系列', '数据准备', '安装', '模型库', '高级教程', '算法介绍', '推理部署', '快速开始'] + # 写根目录下的rst文件 + with open('./index.rst', 'w') as f: + f.write('欢迎使用PaddleClas图像分类库！\n') + f.write('================================\n\n') + f.write('.. toctree::\n') + f.write(' :maxdepth: 1\n\n') + for dir in temp: + f.write(' ' + dir + '/index\n') + f.close() + + # 写各个子目录下的rst文件 + for dir in temp: + for root, dirs, files in os.walk(dir): + print(root) #当前目录路径 + + files.remove('index.rst') + print(files) #当前路径下所有非目录子文件 + curDir = os.path.join(file_dir, dir) + filename = curDir + '/index.rst' + idx = temp.index(dir) + ch_name = chinese_name[idx] + with open(filename, 'w') as f: + f.write(ch_name+'\n') + f.write('================================\n\n') + f.write('.. toctree::\n') + f.write(' :maxdepth: 2\n\n') + + for f1 in files: + f.write(' ' + f1 + '\n') + + f.close() + + +def readfile(filename): + file = open(filename) + i = 0 + while 1: + line = file.readline() + print(i) + print(line) + i += 1 + if not line: + break + pass # do something + file.close() + + +file_name('./') +# filename = './index.rst' +# readfile(filename) \ No newline at end of file diff --git "a/readthedoc\346\214\207\345\215\227.md" "b/readthedoc\346\214\207\345\215\227.md" new file mode 100644 index 00000000..1b201d72 --- /dev/null +++ "b/readthedoc\346\214\207\345\215\227.md" @@ -0,0 +1,161 @@ +1. 注册ReadtheDocs并连接到github + +2. 在github上将项目克隆到本地 + +3. 在本地仓库中安装Sphinx + + ```shell + pip install sphinx + ``` + +4. 创建工程 + + ```shell + sphinx-quickstart + ``` + +5. 对工程进行配置 + + 5.1 更改主题 + + 在source/conf.py中更改或添加如下代码 + + ```python + import sphinx_rtd_theme + html_theme = "sphinx_rtd_theme" + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + ``` + + 5.2 添加markdown支持 + + 首先需要安装recommonmark + + ```shell + pip install recommonmark + ``` + + 在source/conf.py中更改或添加如下代码 + + ```python + from recommonmark.parser import CommonMarkParser + source_parsers = { + '.md': CommonMarkParser, + } + source_suffix = ['.rst', '.md'] + ``` + + 以上五步具体效果可以参考https://www.jianshu.com/p/d1d59d0cd58c + +6. 在创建好项目以后，根目录下应该有如下几个文件： + + - **Makefile**：在使用 `make` 命令时，可以使用这些指令（e.g. `sphinx-build`）来构建文档输出。 + - **_build**：这是触发特定输出后用来存放所生成的文件的目录。 + - **_static**：所有不属于源代码（e.g. 图片）一部分的文件均存放于此处，稍后会在构建目录中将它们链接在一起。 + - **conf.py**：用于存放 Sphinx 的配置值，包括在终端执行 `sphinx-quickstart`时选中的那些值。 + - **index.rst**：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件 + +7. **编写文档**：在 index.rst 文件中的主标题之后，有一个内容清单，其中包括 `toctree` 声明，它将所有文档链接都汇集到 Index。 + + 以根目录下的index.rst为例： + + ```rst + 欢迎使用PaddleClas图像分类库！ + ================================ + + .. toctree:: + :maxdepth: 1 + + models_training/index + introduction/index + image_recognition_pipeline/index + others/index + faq_series/index + data_preparation/index + installation/index + models/index + advanced_tutorials/index + algorithm_introduction/index + inference_deployment/index + quick_start/index + ``` + + 可以用下面的python代码实现根目录和各个子目录下的`index.rst`文件的编写 + + 注意：此代码应该在需要生成文档书的文件夹根目录上运行 + + ```python + import os + + def file_name(file_dir): + temp = [] + for root, dirs, files in os.walk(file_dir): + print(dirs) #当前路径下所有子目录 + temp = dirs #存储需要的子目录 + break + + # 删除不需要的子目录 + temp.remove('images') + temp.remove('_templates') + temp.remove('_build') + temp.remove('_static') + chinese_name = ['模型训练', '介绍', '图像识别流程', '其他', 'FAQ系列', '数据准备', '安装', '模型库', '高级教程', '算法介绍', '推理部署', '快速开始'] + # 写根目录下的rst文件 + with open('./index.rst', 'w') as f: + f.write('欢迎使用PaddleClas图像分类库！\n') + f.write('================================\n\n') + f.write('.. toctree::\n') + f.write(' :maxdepth: 1\n\n') + for dir in temp: + f.write(' ' + dir + '/index\n') + f.close() + + # 写各个子目录下的rst文件 + for dir in temp: + for root, dirs, files in os.walk(dir): + print(root) #当前目录路径 + + files.remove('index.rst') + print(files) #当前路径下所有非目录子文件 + curDir = os.path.join(file_dir, dir) + filename = curDir + '/index.rst' + idx = temp.index(dir) + ch_name = chinese_name[idx] + with open(filename, 'w') as f: + f.write(ch_name+'\n') + f.write('================================\n\n') + f.write('.. toctree::\n') + f.write(' :maxdepth: 2\n\n') + + for f1 in files: + f.write(' ' + f1 + '\n') + + f.close() + + + def readfile(filename): + file = open(filename) + i = 0 + while 1: + line = file.readline() + print(i) + print(line) + i += 1 + if not line: + break + pass # do something + file.close() + + + file_name('./') + # filename = './index.rst' + # readfile(filename) + ``` + +8. 生成文档 + + 运行 `make html` 命令 + +9. 使用浏览器查看在build/html目录下的 `index.html`文件可以查看静态网页 + + + -- GitLab