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']
在工程目次下实行make html，生成完毕后，cd进入build/html/目次下，实行下面下令开启服务器，
显示如下，
此时在外部欣赏器里输入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`
留意：这里显示的目次是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)
此时在教程2.md里添加md的目次语法，
然后重新编译并运行，最后显示如下，可以看到目次正确显示了，
六 总结
本文陈诉了Markdown+Sphinx+Read_the_Docs构建网页时的一些技巧，可以让生成的网页更加美观。别的，也可以看出这些细节都是来自于官方文档，以是遇到题目网上找不到答案就多看看文档，总能解决的。
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。 |
