環(huán)境 本機電腦安裝WSL2捡硅，采用ubuntu18.04
-
安裝
sudo apt-get install python3-pippip3 -
安裝sphinx
pip3 install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark jieba3k
安裝說明
sphinx_rtd_theme ：外觀主題
jieba3k：中文分詞
recommonmark ： 支持Markdown語法
sphinx-autobuild：支持快速創(chuàng)建網(wǎng)站 sphinx-autobuild source build
sphinx ：文檔生成器 命令 make clean 和 make html
-
sphinx-quickstart創(chuàng)建項目
sphinx-quickstart docs 創(chuàng)建一個名叫docs項目泛鸟，此時會讓你回答一些問題
> Separate source and build directories (y/n) [n] ：寫下“y”(不帶引號)，然后按 Enter 冰更。
> Project name ：寫下“Lumache”(不帶引號)，然后按 Enter 昂勒。
> Author name(s) ：寫下“Graziella”(不帶引號)蜀细，然后按 Enter 。
> Project release [] ：寫下“0.1”(不帶引號)并按 Enter 戈盈。
> Project language [en] ：保留為空(默認為英語)奠衔，然后按鍵 Enter 。
完成問題后 塘娶，會生成docs文件夾归斤，文件夾結構如下
7036874418427519 -rwxrwxrwx 1 root root 638 Nov 8 17:33 Makefile
1970324837503974 drwxrwxrwx 1 root root 512 Nov 8 17:33 build
1125899907503778 -rwxrwxrwx 1 root root 804 Nov 8 17:33 make.bat
1688849860793317 drwxrwxrwx 1 root root 512 Nov 8 17:33 source
其中source 是源碼文件夾，進入文件夾修改配置文件conf.py 修改如下
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = '天馬組件'
copyright = '卡奧斯天馬低代碼平臺'
author = '天馬低代碼平臺'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
# 添加extensions 讓他支持recommonmark 也就是markdown語法
extensions = ['recommonmark']
templates_path = ['_templates']
exclude_patterns = []
language = 'zh_CN'
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
# 配置好看的皮膚
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_search_language = 'zh_CN'
# 添加支持md插件
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
numpydoc_show_class_members = False
編譯項目
進入cd docs 目錄
執(zhí)行sphinx-autobuild source build 開始編譯項目 如圖
# sphinx-autobuild source build
[sphinx-autobuild] > sphinx-build /mnt/d/sunbo/Haier/src/lowCode_help_doc/sunbotest/source /mnt/d/sunbo/Haier/src/lowCode_help_doc/sunbotest/build
Running Sphinx v5.1.1
loading translations [cn]... not available for built-in messages
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in build.
[I 221108 17:40:22 server:335] Serving on http://127.0.0.1:8000
[I 221108 17:40:22 handlers:62] Start watching changes
[I 221108 17:40:22 handlers:64] Start detecting changes
此時打開瀏覽器 輸入 http://127.0.0.1:8000 就能看到幫助文檔
同時會在docs目錄下生成build文件夾刁岸，發(fā)布時 使用Nginx作為web服務 掛載build文件夾就行
官網(wǎng)地址https://www.sphinx-doc.org/en/master/
