sphinx 安装

环境 本机电脑安装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：支持快速创建网站 sphinx-autobuild source build
sphinx ：文档生成器 命令 make clean 和 make html

3. sphinx-quickstart创建项目

sphinx-quickstart docs 创建一个名叫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 目录
执行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文件夹，发布时 使用Nginx作为web服务 挂载build文件夹就行

官网地址https://www.sphinx-doc.org/en/master/