Markdown+Sphinx+Read_the_Docs可以用来构建个人主页或知识教程，搭建方法网上很多，可以参考这个大佬的文章。本文主要讲述一些技巧，可以让项目更加完美。
本人运行环境是WSL2 Ubuntu 22.04，Sphinx版本是7.3.7
文章目录
- 一 工程搭建
- 二 安装插件
- 1. Markdown支持插件 --- MyST-Parser
- 2. 其它插件
- 3. 初步配置
- 4. 简单测试
- 三 隐藏指定项
- 四 显示文章目录
- 五 使用Sphinx的事件函数
- 六 总结
一 工程搭建
Sphinx安装好之后，在终端下运行sphinx-quickstart，接着会出现一个选项：是否需要把source目录和build目录分离？
这里选择yes，输入y并回车。分离的好处是工程结构更加清晰。
后续随便填下就行了，最后一个是项目语言，这里选择简体中文zh_CN
至此，工程就搭建好了。
二 安装插件
1. Markdown支持插件 — MyST-Parser
Sphinx默认支持reStructuredText，但是大部分人都是用Markdown来写文章，所以这里就需要安装支持Markdown的插件MyST-Parser，其官网地址是https://myst-parser.readthedocs.io/en/latest/，安装命令如下，
pip install -U myst-parser
其介绍如下，
介绍里提到这个插件是CommonMark-plus，所以就不需要CommonMark了。
2. 其它插件
-
Read the Docs主题插件，
pip install -U sphinx_rtd_theme -
mermaid图表渲染插件
pip install -U sphinxcontrib.mermaid -
代码块一键复制按钮插件
pip install -U sphinx_copybutton
3. 初步配置
使用VSCode打开工程目录，然后在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 = 'demo'
copyright = '2024, WH'
author = 'WH'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
'myst_parser',
"sphinxcontrib.mermaid",
"sphinx_copybutton",
]
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
myst_enable_extensions = [
"tasklist",
"deflist",
"dollarmath",
]
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']
4. 简单测试
在工程目录下执行make html，生成完毕后，cd进入build/html/目录下，执行下面命令开启服务器，
python -m http.server
显示如下，
此时在外部浏览器里输入http://127.0.0.1:8000/，就可以看到生成的网页内容了，
我们在source目录下添加一个目录md，然后在md目录下添加markdown文件，最后md目录里内容如下，
然后在index.rst里添加新建的md文件，特别要注意，md文件名所在行上面要空一行，不能紧邻toctree的配置，否则会解析错误，
.. demo documentation master file, created by
sphinx-quickstart on Tue Jul 9 22:31:30 2024.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to demo's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
md/教程1.md
md/教程2.md
md/教程1_detail/aa.md
md/教程1_detail/bb.md
md/教程2_detail/cc.md
md/教程2_detail/dd.md
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
此时先把服务器停止，然后重新执行make html，最后再开启服务器，浏览器刷新一下，显示如下，
注意：这里显示的目录是md文件中的heading，不是md文件的名字，sphinx是读取md文件内容然后再转成网页。
三 隐藏指定项
可以看出之前的目录会把所有的md文件内容都显示出来，有时我们希望只显示其中一部分，那么就需要使用Sphinx的hidden选项，如下，把目录里的md文件隐藏掉，
PS：这里还启用了通配符功能，使用的是glob选项
重新编译并启动服务器，浏览器显示如下，
可以看到右侧已经如期望那样隐藏了指定的，但是左侧还是跟之前一样，这个时候需要参考一下这个主题的html配置选项，地址是https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html，里面有如下选项，
可以看到这个includehidden，其默认是true，这个是造成上面现象的原因，所以在conf.py里添加这个选项，然后设置为False就可以了，
然后重新编译和运行服务器，最后刷新浏览器，显示如下，
成功！
其它配置项可以根据需要进行添加。
四 显示文章目录
在Markdown里显示目录没有统一标准，不同的Markdown软件会有不同的语法，例如CSDN是@[TOC]，而在Azure Devops里则是[[_TOC_]]，那么在Sphinx里如何显示目录呢？
这个取决于myst_parser，因为它负责把md转成网页，其官网教程是在md文件里添加如下红框中语句，
我们在教程1.md里添加以上语句，然后重新编译并启动服务器，
最后显示如下，可以看到目录正确出现了，
五 使用Sphinx的事件函数
Sphinx的构建分为很多步，每一步都触发对应的事件，如下，图片来自这里，
PS：蓝色框是事件名
每个事件用户都可以添加自定义的函数。
假设现在有个这样的需求：因为md文件有些语法不被myst_parser支持，那么转成网页前就需要先修改md文件里的语句，例如上一节里的目录语法，但是有时不想修改原始md文件内容，那么可以读取完md文件内容时把里面的目录语法替换成myst_parser支持的语法，那么此时可以使用source-read函数，其定义如下，
那么我们在source/conf.py里添加如下2个函数，
def source_read_handler(app, docname, content):
if '[[_TOC_]]' in content[0]:
content[0] = content[0].replace('[[_TOC_]]', '```{contents} Table of Contents\n:depth: 3\n```\n')
def setup(app):
app.connect('source-read', source_read_handler)
source_read_handler()对读取的md内容进行替换，这样就可以满足要求了。
此时在教程2.md里添加md的目录语法，
然后重新编译并运行，最后显示如下，可以看到目录正确显示了，
六 总结
本文讲述了Markdown+Sphinx+Read_the_Docs构建网页时的一些技巧，可以让生成的网页更加美观。另外，也可以看出这些细节都是来自于官方文档，所以遇到问题网上找不到答案就多看看文档，总能解决的。
