reStructuredText

标题（Section Titles）

层级	推荐标题符号
1	=
2	-
3	~
4	^
5	"
6	#
7	*
8	+
9	'

• 每个标题层级用什么标题符号(=,-,~,^,")rst并没有硬性规定

• Simple Table（简单表格）要求每一列的内容宽度要一致，并且分隔线长度要等于最大列的内容宽度

指令块

rst 的“指令块”（directive block）是一种以 .. 指令名:: 开头的特殊语法块，常见的有用于插入特殊内容或结构。

代码块

.. code:: python
    pass

• .. code:: [language]

  • reStructuredText（docutils）原生支持的指令

  • 它可以用来插入格式化的代码块，但不自带语法高亮（除非外部工具支持）

  • 可选参数也可以指定语言（如 .. code:: python），但高亮需要额外工具

.. code-block:: python
    pass

• .. code-block:: [language]

  • Sphinx 对 reStructuredText (rst) 的扩展指令（directive）

  • 支持指定语言并自动高亮

  • 也是 Read the Docs、GitHub rst 渲染、PyPI 等平台支持的主要方式

.. directive-name::
   :option1: value1
   :option2: value2

toctree

.. toctree::
:maxdepth: 2
.. 目录树最多显示到第二级标题
:caption:
.. 目录标题（可选）

• 这表示“目录树”，自动生成导航

  • file1、file2、folder/file3 是你要包含到目录树的 rst 文件（不带 .rst 后缀），路径为相对路径

  • 目录树会自动读取这些文件的标题和结构，并按``maxdepth:`` 指定的层级显示

  • folder 目录下要放一个index.rst文件,这个文件里面也要有 torctree 指令块

  • 这个指令块的maxdepth参数一般写1

.. image:: logo.png
   :width: 200px
   :align: center
   .. 这是插入图片的指令块

.. 这是一个注释，不会显示在文档里

课程表

课程	教师	时间
Python 编程	张老师	周一 10:00-12:00
数据科学	李老师	周三 14:00-16:00

文字块

:: 文字块（literal block）触发符

• :: 是一种语法标记，用来把后面缩进的内容视为“原文块”或“文字块”，即 literal block

• :: 不是指令块

• :: 让后面的内容按照原样排版，不进行格式解析，常用于代码、命令、输出等

::
    .. code-block:: shell
        echo "Hello, World!"

内联代码

``/path/to/source``

echo 111111
# ``/path/to/source``
# 不会显示内联代码块

rst 代码块内不支持再嵌套“内联代码”

超链接

`Google <https://www.google.com/>`_

显示为 Google,且 _ 必不可少