Markdown+Sphinx+Read_the_Docs的一些技巧
Markdown+Sphinx+Read_the_Docs可以用来构建个人主页或知识教程，搭建方法网上许多，可以参考这个大佬的文章。本文告急陈诉一些技巧，可以让项目更加完美。本人运行情况是WSL2 Ubuntu 22.04，Sphinx版本是7.3.7
一 工程搭建
Sphinx安装好之后，在终端下运行sphinx-quickstart，接着会出现一个选项：是否必要把source目次和build目次分离？
https://i-blog.csdnimg.cn/direct/1abe096d50b34e9980a7e154462fb5fd.png
这里选择yes，输入y并回车。分离的好处是工程结构更加清晰。
后续随便填下就行了，最后一个是项目语言，这里选择简体中文zh_CN
https://i-blog.csdnimg.cn/direct/65bd61d26d8b46798101e733515cf86f.png
至此，工程就搭建好了。
二 安装插件
1. Markdown支持插件 — MyST-Parser
Sphinx默认支持reStructuredText，但是大部门人都是用Markdown来写文章，以是这里就必要安装支持Markdown的插件MyST-Parser，其官网地点是https://myst-parser.readthedocs.io/en/latest/，安装下令如下，
pip install -U myst-parser
其先容如下，
https://i-blog.csdnimg.cn/direct/cbd89550c0b441bb98e9becb891b662b.png
先容里提到这个插件是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
显示如下，
https://i-blog.csdnimg.cn/direct/ed50a04492a14170ad175b896ba88ebb.png
此时在外部欣赏器里输入http://127.0.0.1:8000/，就可以看到生成的网页内容了，
https://i-blog.csdnimg.cn/direct/4af3b23af2984f0fa263fca549ede254.png
我们在source目次下添加一个目次md，然后在md目次下添加markdown文件，最后md目次里内容如下，
https://i-blog.csdnimg.cn/direct/3aa486ef0a9e46fea7f96e0901e76acd.png
然后在index.rst里添加新建的md文件，特殊要留意，md文件名地点行上面要空一行，不能紧邻toctree的配置，否则会解析错误，
.. demo documentation master file, created by
sphinx-quickstart on Tue Jul9 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，最后再开启服务器，欣赏器刷新一下，显示如下，
https://i-blog.csdnimg.cn/direct/246ac990b789498d9cb0a572aa03c8d3.png
留意：这里显示的目次是md文件中的heading，不是md文件的名字，sphinx是读取md文件内容然后再转成网页。
三 隐藏指定项
可以看出之前的目次会把所有的md文件内容都显示出来，偶然我们希望只显示其中一部门，那么就必要使用Sphinx的hidden选项，如下，把目次里的md文件隐藏掉，
https://i-blog.csdnimg.cn/direct/2c23cb22df434e50a72cc6f3811d8254.png
PS：这里还启用了通配符功能，使用的是glob选项
重新编译并启动服务器，欣赏器显示如下，
https://i-blog.csdnimg.cn/direct/6e770ba7725a48a98c323012f6998a65.png
可以看到右侧已经如期望那样隐藏了指定的，但是左侧还是跟之前一样，这个时间必要参考一下这个主题的html配置选项，地点是https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html，里面有如下选项，
https://i-blog.csdnimg.cn/direct/0083a5f3594141c5afbc9a295cfdaa53.png
可以看到这个includehidden，其默认是true，这个是造成上面征象的缘故原由，以是在conf.py里添加这个选项，然后设置为False就可以了，
https://i-blog.csdnimg.cn/direct/a03028f871ff49c08f2d2420bea71660.png
然后重新编译和运行服务器，最后刷新欣赏器，显示如下，
https://i-blog.csdnimg.cn/direct/aa536a3d2a394bc1a26bf6b046571cd3.png
成功！
其它配置项可以根据必要进行添加。
四 显示文章目次
在Markdown里显示目次没有统一尺度，不同的Markdown软件会有不同的语法，比方CSDN是@，而在Azure Devops里则是[]，那么在Sphinx里如何显示目次呢？
这个取决于myst_parser，由于它负责把md转成网页，其官网教程是在md文件里添加如下红框中语句，
https://i-blog.csdnimg.cn/direct/2595138746ab42ec96b8429aee94a316.png
我们在教程1.md里添加以上语句，然后重新编译并启动服务器，
https://i-blog.csdnimg.cn/direct/50570a40a92a4ec5820ddf41acad43e1.png
最后显示如下，可以看到目次正确出现了，
https://i-blog.csdnimg.cn/direct/d37935e0748e41cd89ca8c5246e40e45.png
五 使用Sphinx的变乱函数
Sphinx的构建分为许多步，每一步都触发对应的变乱，如下，图片来自这里，
https://i-blog.csdnimg.cn/direct/1e32bc31f06044438843873b6feaacae.png
PS：蓝色框是变乱名
每个变乱用户都可以添加自界说的函数。
假设现在有个如许的需求：由于md文件有些语法不被myst_parser支持，那么转成网页前就必要先修改md文件里的语句，比方上一节里的目次语法，但是偶然不想修改原始md文件内容，那么可以读取完md文件内容时把里面的目次语法替换成myst_parser支持的语法，那么此时可以使用source-read函数，其界说如下，
https://i-blog.csdnimg.cn/direct/bf5492b1e36a453c84ceff62062b6768.png
那么我们在source/conf.py里添加如下2个函数，
def source_read_handler(app, docname, content):
if '[]' in content:
content = content.replace('[]', '```{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的目次语法，
https://i-blog.csdnimg.cn/direct/a33e0bb9e7c6463198ea25e349c53ac7.png
然后重新编译并运行，最后显示如下，可以看到目次正确显示了，
https://i-blog.csdnimg.cn/direct/66570b6de10c44fe91cc78fc1f4bc9b1.png
六 总结
本文陈诉了Markdown+Sphinx+Read_the_Docs构建网页时的一些技巧，可以让生成的网页更加美观。别的，也可以看出这些细节都是来自于官方文档，以是遇到题目网上找不到答案就多看看文档，总能解决的。
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
页:
[1]