Python rich-rst 完整使用文档

一、包基础概述

1. 核心定义

rich-rst 是基于 rich 终端美化库开发的ReStructuredText（reST）终端渲染插件，作用是在命令行终端内直接格式化渲染 .rst 文档、reST 字符串，无需浏览器/文档工具，实现终端内带样式、表格、代码块、标题、列表、警告框、图片占位的结构化文档预览。

2. 核心依赖

• 底层：rich（终端富文本渲染核心）
• 解析引擎：docutils（标准 reST 语法解析库）
• 辅助：pygments（代码高亮）

3. 核心功能

1. 终端渲染完整 reST 语法：多级标题、有序/无序列表、定义列表、引用块、注释
2. 代码块语法高亮（Python/Shell/JSON/C++等），支持行号、边框
3. 表格自动适配终端宽度、对齐、单元格跨行跨列
4. 提示框/警告框/错误框/注释框（note/warning/danger/tip 指令）
5. 超链接、行内强调（粗体/斜体/等宽代码）、下标上标
6. 本地 .rst 文件一键读取渲染、字符串直接渲染
7. 自定义主题、边框样式、颜色、缩进、最大宽度
8. 配合 rich 控制台组件集成到 CLI 工具、日志、帮助文档

二、安装方式

标准安装（稳定版）

pip install rich-rst

完整依赖安装（含docutils/pygments，避免解析报错）

pip install rich-rst rich docutils pygments

开发版（GitHub源码）

pip install git+https://github.com/.../rich-rst.git

校验安装成功

import rich_rst
print(rich_rst.__version__)

三、核心语法、类与参数详解

3.1 核心导出类/函数

接口	作用
RST	主渲染类，接收 reST 文本/文件路径，可打印、转换为 rich 组件
print_rst()	快捷函数，直接输出 reST 内容到终端
read_rst_file(path)	读取本地rst文件返回渲染对象
rst_to_panel()	将 reST 转为 rich Panel 面板嵌入界面

3.2 RST 类初始化参数

RST(
    content: str = "",          # reST 文本字符串
    filepath: str = None,       # 本地.rst文件路径，二选一
    width: int | None = None,   # 渲染最大宽度，None=自动适配终端
    code_theme: str = "monokai",# 代码高亮主题，pygments全部主题可用
    show_line_numbers: bool = False, # 代码块是否显示行号
    syntax_highlight: bool = True,    # 是否开启代码高亮
    theme: str = "default",     # 文档整体配色主题
    border_style: str = "round",# 表格/面板边框：round/solid/dashed/double
    warn_unknown_directives: bool = True, # 未知reST指令是否输出警告
    tab_size: int = 4,          # reST缩进制表符宽度
)

3.3 常用方法

1. .render()：返回 rich 可打印组件（Panel/Group）
2. .print()：直接打印到控制台
3. .get_text()：返回纯无样式文本（去除所有终端颜色）
4. .save_html(path)：将渲染结果导出为 HTML 文件

3.4 print_rst 快捷函数参数

print_rst(
    content,
    console: Console = None,    # 指定自定义rich控制台
    **kwargs                    # 全部RST类初始化参数通用
)

3.5 支持的标准 reST 语法子集

1. 标题：===== / ----- / ^^^^^ 多级层级
2. 行内标记：**粗体** *斜体* `等宽代码`
3. 列表：无序列表 -、有序列表 1.、定义列表 key :: value
4. 代码块：.. code-block:: python
5. 指令：.. note:: / .. warning:: / .. danger:: / .. tip::
6. 表格：简单网格表、简易表
7. 链接：链接文本 <https://xxx.com>_
8. 引用块：缩进文本 + .. 注释

四、8个完整可运行实战案例

案例1：基础字符串reST直接打印（入门）

from rich_rst import print_rst

rst_text = """
======= 工具说明 =======
这是 **rich-rst** 基础演示
- 支持无序列表
- 终端实时渲染
行内代码：`print("hello")`

.. note::
    基础用法：print_rst 一键输出
"""

print_rst(rst_text)

案例2：读取本地 .rst 文件渲染

新建 doc.rst

==== 配置说明 ====
端口配置：默认 8080
.. code-block:: json
    {
        "host": "0.0.0.0",
        "port": 8080
    }

读取渲染代码：

from rich_rst import read_rst_file

rst_doc = read_rst_file("doc.rst", show_line_numbers=True)
rst_doc.print(width=100)

案例3：带语法高亮代码块（多语言）

from rich_rst import RST

code_rst = """
Python 示例
.. code-block:: python
    def demo():
        return 1 + 2

Shell 命令
.. code-block:: bash
    pip install rich-rst
"""

render = RST(content=code_rst, code_theme="github-light", show_line_numbers=True)
render.print()

案例4：渲染带表格的结构化文档

from rich_rst import print_rst

table_rst = """
==== 设备清单 ====

+--------+--------+-------+
| 型号   | 系统   | 数量  |
+--------+--------+-------+
| HXD1C  | 机车   | 12    |
| SS4B   | 货运   | 8     |
+--------+--------+-------+

.. warning::
    表格宽度自动适配终端，超长自动换行
"""
print_rst(table_rst, border_style="double")

案例5：嵌入 rich 复合面板（CLI界面整合）

from rich.console import Console
from rich.panel import Panel
from rich_rst import rst_to_panel

console = Console()

rst_content = """
==== 操作指引 ====
1. 启动服务：`python main.py start`
2. 查看日志：`logs/show.log`

.. tip::
    后台运行添加参数 --daemon
"""

# 转为rich Panel嵌入界面
panel = rst_to_panel(rst_content, title="帮助文档")
console.print(Panel(panel, title="系统工具箱"))

案例6：区分提示/警告/危险多类型提示框

from rich_rst import print_rst

alert_rst = """
提示、警告、错误区分演示

.. tip::
    优化：使用tab_size=2缩小缩进

.. note::
    支持全部 pygments 代码主题

.. warning::
    缺失docutils会导致解析失败

.. danger::
    生产环境不要关闭语法高亮校验
"""
print_rst(alert_rst, width=80)

案例7：提取纯文本（去除终端颜色，用于日志保存）

from rich_rst import RST

rst_text = """
# 版本日志
**v1.0.1**
- 修复表格渲染bug
"""

rst_obj = RST(content=rst_text)
# 终端带色打印
rst_obj.print()
# 获取纯文本无样式
plain_text = rst_obj.get_text()
print("纯文本内容：\n", plain_text)
# 写入文件
with open("plain_doc.txt", "w", encoding="utf-8") as f:
    f.write(plain_text)

案例8：CLI工具内置帮助文档（命令行程序集成）

import argparse
from rich_rst import print_rst

# 命令行参数
parser = argparse.ArgumentParser()
parser.add_argument("--help-doc", action="store_true", help="显示完整rst帮助文档")
args = parser.parse_args()

# 内置reST帮助文档
help_rst = """
======== 运维工具 v2.0 ========
工具用途：机车运行数据解析

子命令列表
1. parse  解析GYK记录文件
2. export 导出报表
3. check  风险校验

.. code-block:: shell
    # 示例命令
    python tool.py parse data.gyk --out report.xlsx
"""

if args.help_doc:
    print_rst(help_rst, width=120, code_theme="dracula")

五、常见错误、报错原因与解决方案

错误1：ModuleNotFoundError: No module named ‘rich_rst’

• 原因：未安装包，或虚拟环境未激活
• 解决：

pip install rich-rst rich docutils pygments

错误2：DocutilsImportError / 解析rst时报错无法解析指令

• 原因：缺少 docutils 依赖，仅装了rich-rst
• 解决：pip install docutils

错误3：代码块无高亮，全部白色文字

• 原因：缺少pygments；code_theme名称写错；syntax_highlight=False
• 修复：

RST(content=text, syntax_highlight=True, code_theme="monokai")
pip install pygments

错误4：读取rst文件报UnicodeDecodeError

• 原因：文件非utf-8编码（GBK/GB2312）
• 解决：手动读取文件指定编码再传入RST

with open("doc.rst", "r", encoding="gbk") as f:
    text = f.read()
RST(content=text)

错误5：Unknown directive type “xxx” 终端警告

• 原因：使用了reST扩展指令（sphinx专属指令，rich-rst不支持）
• 处理：
  1. 删除sphinx独有指令（automodule/toctree等）
  2. 关闭警告：warn_unknown_directives=False

错误6：表格显示错乱、文字重叠

• 原因：终端宽度过小，未指定width；制表符tab_size过大
• 修复：限制宽度、缩小缩进

print_rst(text, width=90, tab_size=2)

错误7：print() 打印RST对象只输出内存地址，无样式

• 原因：直接print实例，未调用.print()或.render()
• 错误写法：print(RST(text))
• 正确写法：

rst = RST(text)
rst.print()
# 或使用rich控制台渲染
from rich.console import Console
c = Console()
c.print(rst.render())

错误8：中文乱码、方块问号

• 原因：终端不支持utf-8；Windows cmd默认gbk编码
• 解决：
  1. Windows终端执行 chcp 65001
  2. 代码开头设置环境变量：

import os
os.environ["PYTHONIOENCODING"] = "utf-8"

六、使用注意事项与最佳实践

1. 语法兼容限制

1. rich-rst 仅支持基础标准reST，不兼容Sphinx扩展语法（toctree、autodoc、figure、自定义sphinx指令），sphinx项目文档直接渲染会大量警告。
2. 不支持复杂图像嵌入，.. image:: 仅显示占位文本，无法加载本地图片。
3. 复杂数学公式 math 指令无渲染支持。

2. 性能优化

1. 超大rst文件（>5000行）建议关闭代码行号 show_line_numbers=False 提升渲染速度。
2. 循环多次渲染同一文档，复用RST实例，不要重复创建。
3. 后台服务/日志场景使用 .get_text() 获取纯文本，避免持续生成ANSI颜色字符占用内存。

3. 跨平台适配

1. Windows CMD边框样式推荐 solid，round 圆角会显示方块乱码；Windows Terminal/PowerShell完整支持全部边框。
2. 统一设置 tab_size=4 保证Windows/Linux缩进一致。

4. 安全规范

1. 禁止渲染外部不可信rst文件：恶意构造超长表格、递归嵌套列表会触发终端卡死、内存溢出。
2. 自动化工具读取外部文档时增加最大宽度限制 width=100，限制渲染负载。

5. 开发集成规范

1. CLI帮助文档优先使用 print_rst()，极简无需额外控制台对象。
2. 与rich Table/Progress/Panel混合界面时使用 rst_to_panel() 转换组件嵌入。
3. 日志输出使用 .get_text() 去除ANSI颜色码，避免日志文件充斥转义字符。

6. 主题选择建议

• 浅色终端：github-light、vs
• 深色终端：monokai、dracula、solarized-dark

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。