reStructuredText语法笔记
##########################

章节等级编号符号
*******************

一般来说，reST语法不规定什么符号作为几级标题，不过可以参考python文档的约定俗成的习惯顺序字符进行使用。

| Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings.
| 一般来说，没有标题级别被分配给确定的字符，因为(目录)结构被标题的连续(继承)性所确定。

| However, for the Python documentation, here is a suggested convention:
| 但是，对于Python文档，这里是一个建议的惯例:

推荐的标题字符使用：
======================
| ``#``, with overline, for parts（部分/篇章）
| ``*``, with overline, for chapters（章节）
| ``=``, for sections（节）
| ``-``, for subsections（小节）
| ``^``, for subsubsections（再小节/小小节）
| ``"``, for paragraphs（段落）


.. note:: 
    | 常见书籍的结构大致有：

    | 一、书籍宏观结构
    |     **Volume（卷）**
    |     **Book（册）**
    |     **Part（部分）**

    | 二、核心章节层级
    |     **Chapter（章）**
    |     **Section（节）**
    |     **Subsection（小节）**

    | 三、微观内容结构
    |     **Paragraph（段落）**
    |     **Sentence（句子）**

    | 四、特殊场景术语
    |     **Article（条）**
    |     **Clause（条款）**
    |     **Appendix（附录）**

    | 五、辅助结构术语
    |     **Prologue（序章） & Epilogue（后记）**
    |     **Preface（前言） & Afterword（跋）**
    |     **Index（索引） & Glossary（术语表）**


引文和代码块
*************

使用缩进一段或几段文本来实现类似 markdown 文档中 ``>`` 的效果。

可以选择这两种实现方式：

+使用 ``::`` 将文本块转换为代码块，保留源文本格式
=================================================

.. code-block:: rst
    
    This is a normal text paragraph. The next paragraph is a code sample::

        It is not processed in any way, except
        that the indentation is preserved.


        It can span multiple lines.

    This is a normal text paragraph again.

其渲染结果为:

This is a normal text paragraph. The next paragraph is a code sample::

    It is not processed in any way, except
    that the indentation is preserved.


    It can span multiple lines.

This is a normal text paragraph again.

+不使用 ``::`` 将文本块作为普通段落处理
=======================================

.. code-block:: rst

    This is a normal text paragraph. The next paragraph is a code sample

        It is not processed in any way, except
        that the indentation is removed.


        It can span multiple lines.

    This is a normal text paragraph again.

其渲染结果为:

This is a normal text paragraph. The next paragraph is a code sample

    It is not processed in any way, except
    that the indentation is removed.


    It can span multiple lines.

This is a normal text paragraph again.



插入图片
*************

行间图片：
===========
使用 ``image`` 指令插入行间图片，其格式如下（仅列举常用参数）：


.. code-block:: rst

    .. image:: [相对路径/]icon.png
        :alt: [图标描述]
        :width: [强制指定宽度](24px/50%/...)
        :height: [强制指定高度](24px/50%/...)
        :align: [文中对齐方式]("left", "center", "right"...)
        :target: [图片的点击链接](_blank / https://example.com)

示例：

代码示例：

.. code-block:: rst

    这是第一段文字，将在后面插入一个居中的图片，仅限制高度等比例缩放：

    .. image:: 语法笔记-img/B站图标示例.png
        :alt: 测试图片-链接到B站
        :height: 100px
        :align: center
        :target: https://www.bilibili.com/

    以上是示例图片，到本行本示例结束。


渲染效果：

--------

这是第一段文字，将在后面插入一个居中的图片，仅限制高度等比例缩放：

.. image:: 语法笔记-img/B站图标示例.png
    :alt: 测试图片-链接到B站
    :height: 100px
    :align: center
    :target: https://www.bilibili.com/

以上是示例图片，到本行本示例结束。

--------

行内图片：
===========

若要在段落文本内行内插入图片（而非独占一行），可以通过 ``||`` 符号定义 **「替换引用」** 实现。具体步骤如下：

1. 定义行内图片占位符所使用的图片\:
---------------------------------------
在文档中任一位置（通常放在文档开头或专门的替换引用区），使用如下格式定义图片替换引用：

.. code-block:: rst

  .. |占位符标识符| image:: [相对路径/]img.png
      :alt: [图片描述]
      :width: [强制指定宽度](24px/50%/...)
      :height: [强制指定高度](24px/50%/1em...)
      :align: [行内对齐方式]("top", "middle", "bottom", "baseline"...(仅测试了"middle"))
      :target: [图片的点击链接](_blank / https://example.com)


1. 在段落文本中通过占位符 ``|[占位符标识符]|`` 插入图片\:
-----------------------------------------------------------------

.. code-block:: rst

  这是包含行内图片的文本示例： |占位符标识符|，图片将与文字在同一行显示。



示例：

代码示例：

.. code-block:: rst

    这是第一段文字，将在本句结尾插入一个垂直居中的图片:|占位符标识符1|;
    图片高度被限制为一倍行高，图片将在本行后定义。

    .. |占位符标识符1| image:: 语法笔记-img/GitHub_icon.png
        :alt: 测试图片-链接到 "https://github.com/"
        :height: 1em
        :align: middle
        :target:  https://github.com/

    以上示例到本行本示例结束。


渲染效果：

--------

这是第一段文字，将在本句结尾插入一个垂直居中的图片:|占位符标识符1|;
图片高度被限制为一倍行高，图片将在本行后定义。

.. |占位符标识符1| image:: 语法笔记-img/GitHub_icon.png
    :alt: 测试图片-链接到 "https://github.com/"
    :height: 1em
    :align: middle
    :target:  https://github.com/

以上示例到本行本示例结束。

--------












Admonition 指令
********************

reStructuredText 提供多种预定义的警告指令（Admonitions），用于突出显示特定类型的内容。

各指令的功能和适用场景
===========================

.. list-table:: 
   :header-rows: 1
   :widths: 20 40 40

   * - 指令名称
     - 功能说明
     - 典型使用场景
   * - ``note``
     - 中性补充信息，不强调重要性或风险
     - 附加说明、背景知识、扩展解释
   * - ``tip``
     - 建议或优化实践，强调实用性
     - 推荐技巧、效率提升方法
   * - ``hint``
     - 提示可能被忽略的细节
     - 隐藏功能、快速操作、便捷选项
   * - ``important``
     - 强调关键信息，需特别注意
     - 必须遵循的规则、核心概念
   * - ``warning``
     - 警示潜在风险（中等严重性）
     - 功能异常风险、兼容性问题
   * - ``caution``
     - 比 warning 更严重，可能导致数据丢失
     - 数据修改操作、临时性限制
   * - ``danger``
     - 最高级别危险警告
     - 硬件损坏、不可逆数据损失
   * - ``error``
     - 指出错误场景或常见误区
     - 错误示例、调试建议、反模式
   * - ``attention``
     - 需要主动关注的内容
     - 易混淆点、需人工确认的步骤

示例用法
=============

基础语法示例
-------------------

.. code-block:: rst

   .. note:: 
       This is a **note** admonition.
       - 支持多行内容
       - 可包含 **强调** 等格式

   .. warning:: 直接使用简写语法
       内容从第二行开始缩进

渲染效果：

.. note:: 
   This is a **note** admonition.
   - 支持多行内容
   - 可包含 *强调* 等格式

.. warning:: 直接使用简写语法
   内容从第二行开始缩进

带标题的高级用法
-----------------------

.. code-block:: rst

   .. admonition:: 自定义标题（扩展用法）
      :class: attention

      通过组合 ``admonition`` 指令和 CSS 类，
      可以模拟标准警告样式

   .. danger:: 格式化硬盘！
       **操作不可逆**，请确认：
       
       1. 已备份重要数据
       2. 已关闭所有应用程序

渲染效果：

.. admonition:: 自定义标题（扩展用法）
   :class: attention

   通过组合 ``admonition`` 指令和 CSS 类，
   可以模拟标准警告样式

.. danger:: 格式化硬盘！
    **操作不可逆**，请确认：
    
    1. 已备份重要数据
    2. 已关闭所有应用程序



Admonition 指令支持嵌套其他 reST 元素（列表、代码块等）,支持使用 ``:class:`` 选项可自定义样式。


不同 **Admonition指令** 渲染样式参考：
-----------------------------------------


1. ``note``
示例程序：

.. code-block:: rst

   .. note:: 
       这是一个 "note" 指令。

渲染效果：

.. note:: 
    这是一个 "note" 指令。

--------------------------------

2. ``tip``
示例程序：

.. code-block:: rst

   .. tip:: 
       这是一个 "tip" 指令。

渲染效果：

.. tip:: 
    这是一个 "tip" 指令。

--------------------------------

3. ``hint``
示例程序：

.. code-block:: rst

   .. hint:: 
       这是一个 "hint" 指令。

渲染效果：

.. hint:: 
    这是一个 "hint" 指令。

--------------------------------

4. ``important``
示例程序：

.. code-block:: rst

   .. important:: 
       这是一个 "important" 指令。

渲染效果：

.. important:: 
    这是一个 "important" 指令。

--------------------------------

5. ``warning``
示例程序：

.. code-block:: rst

   .. warning:: 
       这是一个 "warning" 指令。

渲染效果：

.. warning:: 
    这是一个 "warning" 指令。

--------------------------------

6. ``caution``
示例程序：

.. code-block:: rst

   .. caution:: 
       这是一个 "caution" 指令。

渲染效果：

.. caution:: 
    这是一个 "caution" 指令。

--------------------------------

7. ``danger``
示例程序：

.. code-block:: rst

   .. danger:: 
       这是一个 "danger" 指令。

渲染效果：

.. danger:: 
    这是一个 "danger" 指令。

--------------------------------

8. ``error``
示例程序：

.. code-block:: rst

   .. error:: 
       这是一个 "error" 指令。

渲染效果：

.. error:: 
    这是一个 "error" 指令。

--------------------------------

9. ``attention``
示例程序：

.. code-block:: rst

   .. attention:: 
       这是一个 "attention" 指令。

渲染效果：

.. attention:: 
    这是一个 "attention" 指令。