環(huán)境 本機電腦安裝WSL2，采用ubuntu18.04

1. 安裝sudo apt-get install python3-pip pip3

2. 安裝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

3. 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文件夾，文件夾結(jié)構(gòu)如下

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/