使用场景
写文档的工具有很多，静态文档也有很多站点工具软件，像Hexo、Hugo、Jekyll等生态也挺好的，今天我想介绍的是一款Python模块里面的Sphinx-Doc文档，我主要用它的目的是根据Markdown文档生成站点，并且可以生成静态Html文件，也能本地浏览。我相信其他产品也能做到，但是没仔细研究，它的一个功能比较吸引我，是生成的文档有带导航栏的目录，主题模板也算丰富，够用。
主要是我要把我的文档提供给无法上网的人离线用，其实就是离线的使用手册一类的需求。
安装Sphinx
我是用Python3来安装和使用的，也可以参考官方安装（反正我用Mac装了命令无法使用）。
请额外建一个目录来开始安装和存放你的文档，然后在用Python虚拟机的方式来安装并使用。
打开一个命令行终端， cd 放到您刚刚创建的目录中，然后运行以下命令：
$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx
备注
上面使用的安装方法更详细地描述在 从PYPI安装 。在本教程的其余部分中，这些说明将假定为一个Python虚拟环境。
如果正确执行了这些指令，您应该可以使用Sphinx命令行工具。您可以运行以下命令执行基本验证：
(.venv) $ sphinx-build --version
sphinx-build 4.0.2
如果您看到类似的输出，那么就是安装成功了！
然后从命令行运行以下命令：
(.venv) $ 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]：保留为空(默认为英语，中文输入：zh_CN)，然后按键 Enter 。
在最后一个问题之后，您将看到新的 docs 目录中包含以下内容。
docs
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
这些文件中的每个文件的目的是：
build/
一个空目录(目前)，它将保存呈现的文档。make.batandMakefile
方便的脚本可以简化一些常见的Sphinx操作，比如呈现内容。source/conf.py
保存Sphinx项目配置的一个Python脚本。它包含您为指定的项目名称和版本sphinx-quickstart，以及一些额外的配置密钥。source/index.rst
这个 root document作为欢迎页面，并包含“目录树”的根(或 toctree )。
多亏了这个自举步骤，您已经具备了第一次将文档呈现为HTML所需的一切。为此，请运行以下命令：
(.venv) $ sphinx-build -M html docs/source/ docs/build/
最后，打开 docs/build/html/index.html 在您的浏览器中。您应该会看到类似这样的内容：
安装插件
如果是默认的情况是不支持md格式文件的，需要装插件。如果有喜欢的主题也可以进行安装，下面我把这个过程演示一遍。
主题地址（大家自行去选择合适自己的主题）：https://sphinx-themes.org/
支持markdown文件
pyhton3 pip install recommonmark
安装sphinx_rtd_theme主题
pyhton3 pip install furo
安装sphinx_markdown_tables表格支持
pyhton3 pip install sphinx_markdown_tables
修改文件夹下的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 = 'XXXX'
copyright = '2024, cookie.joo'
author = 'cookie.joo'
release = ''
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
# 插件
extensions = ['recommonmark','sphinx_markdown_tables']
# 主题
html_theme = 'furo'
templates_path = ['_templates']
exclude_patterns = []
language = 'en'
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_static_path = ['_static']
把写好的md文档放到source文件夹下，Sphinx会识别到，并修改index.rst文件，该文件是首页定义文件。
.. FTD部署文档 documentation master file, created by
sphinx-quickstart on Tue Jun 4 16:00:05 2024.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to FTD快速部署 documentation!
=======================================
.. toctree::
:maxdepth: 2
:caption: Contents:
###这里把你的md文档定义到这里，打包会扫描到下面定义的文件，如果是带文件夹就这么描述
test/jdk
###不带文件夹就这么描述，可以把.md后缀加上也可以不加后缀
docker
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
请运行以下命令：
## 到docs文件夹下
(.venv) $ cd docs
## 使用这个简易命令更方便，其中如果要重新生成完整的html文件就要先清理再生成，否则只会更新修改后的
(.venv) $ make clean
(.venv) $ make html
问题处理
问题1：md文档的代码块格式无法支持或无法识别
正在写入输出……[100%] infra-ftd-ops/log
/Users/cookie.joo/Desktop/test/docs/source/infra-ftd-ops/log.md:: WARNING: Lexing literal_block 'function check_pid() {\n pidfile="/app/qadmin/filebeat/filebeat.pid"\n if [ -f $pidfile ];then\n pid=`cat $pidfile`\n if [ -n $pid ]; then\n running=`ps -p $pid|grep -v "PID TTY" |wc -l`\n return $running\n fi\n fi\n return 0\n}\nfunction start_filebeat() {\n pidfile="/app/qadmin/filebeat/filebeat.pid"\n if [ ! -f "/app/qadmin/filebeat/logs" ]; then\n mkdir /app/qadmin/filebeat/logs -p\n fi\n nohup /app/qadmin/filebeat/bin/filebeat -c /app/qadmin/filebeat/etc/filebeat.yml --path.home /app/qadmin/filebeat --path.config /app/qadmin/filebeat/etc --path.data /app/qadmin/filebeat/data --path.logs /app/qadmin/filebeat/logs >> /app/qadmin/filebeat/logs/root.log 2>&1 &\n echo $! > $pidfile\n echo "filebeat started..., pid=$!"\n}\nfunction run_daemon() {\n check_pid\n running=$?\n if [ $running -eq 0 ];then\n start_filebeat\n fi\n}\npython3 update_filebeat.py\nrun_daemon\n' as "python" resulted in an error at token: '$'. Retrying in relaxed mode.
正在生成索引... genindex 完成
正在写入附加页面... search 完成
正在复制图像文件……[100%] infra-ftd-ops/images/log/image.png
正在导出 English (code: en) 的搜索索引... 完成
正在导出对象清单... 完成
构建成功, 1 条警告。
这个问题就是我指定了代码块是python格式，但是内容格式不正确，就报出来了，反正改对就行。
还有就是md有些格式这个插件无法识别的，把他改成bash或者不设置代码块的格式就好了。
问题2：新增的页面没有加到首页里面的警告，这个告警好像也会影响打包的问题。
正在更新环境：有 0 个新增文件，有 1 个文件已被修改，有 0 个文件已被移除
正在读取源文件……[100%] index
/Users/cookie.joo/Desktop/test/docs/source/index.rst:9: WARNING: 目录树中引用的文档 'test/nginx' 不存在
/Users/cookie.joo/Desktop/test/docs/source/index.rst:9: WARNING: 目录树中引用的文档 'test/service-api' 不存在
/Users/cookie.joo/Desktop/test/docs/source/index.rst:9: WARNING: 目录树中引用的文档 'test/agent' 不存在
正在查找当前已过期的文件……没有找到已过期文件
正在 Pickle 序列化环境... 完成
正在校验一致性... /Users/cookie.joo/Desktop/test/docs/source/test/agent.md: WARNING: 文档没有加入到任何目录树中
/Users/cookie.joo/Desktop/test/docs/source/test/log.md: WARNING: 文档没有加入到任何目录树中
完成
正在准备写入文档... 完成
正在复制资产文件... 正在复制静态文件... 完成
正在复制额外文件... 完成
问题3：引用的图片不存在
/Users/cookie.joo/Desktop/test/.venv/lib/python3.10/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document
warn("Container node skipped: type={0}".format(mdnode.t))
/Users/cookie.joo/Desktop/test/docs/source/test/jenkins.md:: WARNING: 无法读取图像文件：test/images/jenkins/image.png
正在查找当前已过期的文件……没有找到已过期文件
正在 Pickle 序列化环境... 完成
正在校验一致性... 完成
注意📢：一定要把这些异常给消除，否则重新打包异常就不会有任何更新。
最后
打包编译后的代码都在build/html文件夹下，我关注的就是这个，我要打包这个目录给别人离线使用的。
