学习 Sphinx 的 rst 文件语法

发表于 2022-05-18 更新于 2022-05-31 分类于 docs Changyan：本文字数： 2.5k 阅读时长 ≈ 2 分钟

学习一下Sphinx。

⚔️ 基本语法

字体

两侧必须留有空格或者. ！！

斜体: *hello*

粗体: **hello**

等宽 `hello`

段落

换行左对齐就是段落！！


段落 1
  哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈

段落 2
  哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈

段落 3
  哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈

列表

列表前后, 以及条目之间空行隔开，可以用 #. 插中间跨编号，而且第一条的序号不必从 1 开始！！

有序列表

1. 项目 1

  1. 项目 1 - 1

  2. 项目 1 - 2

b. 项目 2

  1. 项目 2 - 1

  2. 项目 2 - 2

A. 项目 3

  3. 项目 3 - 3

  #. 项目 3 - 2

  9. 项目 3 - 9

无序列表

和 markdown 差不多！！

* 列表第一级

  + 第二级

    - 第三级

  + 第二级的另一个项目

嵌入程序

片段代码：.. code-block:: 语言名
行内代码：:code:`code` ！！

.. code-block:: python

  def test():
    print('hello world').

:code:`print('hello world')` is code in line.

章节

有 ====、----、^^^^、#### 等许多等级，在标题的上面也可以加 ==== ！！

标题
====

章
----

节
^^^^

小节
#####

表格

一般表格

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

简单表格

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

CSV 表格

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

列表表格

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

插图

.. image:: _static/pomin.jpg

嵌入视频

.. raw:: html

  <iframe height=498 width=510 src='....' frameborder=0 'allowfullscreen'></iframe>

超链接

RST 中会自动将链接转为超链接，对于一些可能导致错误的需要使用 `...<....>`_ 强调为链接！！


http://pomin.top

`Title <http://link>`_

提示

.. warning::

  warning 警告

.. danger::

  danger 警惕

.. note::

  note 笔记

.. tip::

  tip 提示

一个 read the docs 提供的配置项提示 ( 需要 conf.py 支持 )

.. confval:: conf

    . . . . . . .

import sphinx_rtd_theme
from sphinx.locale import _

# Extensions to theme docs
def setup(app):
    from sphinx.domains.python import PyField
    from sphinx.util.docfields import Field
    app.add_object_type(
        'confval',
        'confval',
        objname='configuration value',
        indextemplate='pair: %s; configuration value',
        doc_field_types=[
            PyField(
                'type',
                label=_('Type'),
                has_arg=False,
                names=('type',),
                bodyrolename='class'
            ),
            Field(
                'default',
                label=_('Default'),
                has_arg=False,
                names=('default',),
            ),
        ]
    )

注释

.. 注释 ( 后面不能跟 :: ) ！！

.. hello (Can't be seen) !!

🛠️ 引用、目录

引用

名称后面加下划线！！


.. csv-table::
  :name: CSV

插图
-----------------------

跳转到手动添加 :name: 属性的 CSV 表格 : CSV_

跳转到标题属性的 插图: 插图_