用 Sphinx 和 readthedocs 主题搭建一个说明文档

看到 ESP-IDF、韦东山老师的文档网站布局十分相似，看到都是用 Sphinx 这个工具搭建的，学习一下。

Sphinx 官方文档: https://github.com/sphinx-doc/sphinx
myst-parser 官方文档: https://myst-parser.readthedocs.io
Read the docs 官方文档: https://github.com/readthedocs/readthedocs.org

🌐 安装 Sphinx、Read the docs 主题

pip 版本不能过低，这里使用 Ubuntu 18.04 LTS 和 pip 22.0.4

pip install -U sphinx
pip install sphinx-rtd-theme

🔑 运行 Sphinx 和 readthedocs

配置并使用主题

sphinx-quickstart

后面按需要选择和输入，这些配置项大都在 Makefile 和 conf.py 中

• conf.py 中修改主题为：sphinx_rtd_theme，配置如下

project = "pomin's docs"
copyright = '2022, pomin'
author = 'pomin'

release = "pomin's docs"

extensions = []

exclude_patterns = []

html_theme = "sphinx_rtd_theme"

html_static_path = ['_static']

构建到 HTML

build 文件夹中打开示例界面

✨ 适配 Markdown 文件

配置

pip install --upgrade myst-parser

• 增加拓展到 conf.py 配置如下

project = "pomin's docs"
copyright = '2022, pomin'
author = 'pomin'

release = "pomin's docs"

extensions = ['myst_parser']

templates_path = ['_templates']

exclude_patterns = []

html_theme = "sphinx_rtd_theme"

html_static_path = ['_static']


source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

简单测试

• 目录

• index.rst

.. pomin's docs

context 1
==========================

Hello context 1

context 2
==========================

Hello context 2


.. toctree::
   :caption: Theme Documentation
   :maxdepth: 2
   :hidden:

   test-md

.. toctree::
   :maxdepth: 1
   :hidden:

   test-rst

• test-md.md

# md page

This is a Markdown page

• test-rst.rst

rst page
========================

This is a rst page

最终效果

站点: https://docs.pomin.top/

至于 rst 文件的语法，后面再学习学习。。

⚡⚡⚡ OVER ⚡⚡⚡