Markdown+Sphinx+Read_the_Docs的一些技巧

Markdown+Sphinx+Read_the_Docs可以用来构建个人主页或知识教程，搭建方法网上很多，可以参考这个大佬的文章。本文主要讲述一些技巧，可以让项目更加完美。

本人运行环境是WSL2 Ubuntu 22.04，Sphinx版本是7.3.7

一 工程搭建

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构建网页时的一些技巧，可以让生成的网页更加美观。另外，也可以看出这些细节都是来自于官方文档，所以遇到问题网上找不到答案就多看看文档，总能解决的。