用于 Python 文档的 reStructuredText

将 Markdown 转换为 RST 用于 Sphinx 和 Python 项目

reStructuredText (RST) 是使用 Sphinx 的 Python 项目的标准文档格式。虽然 Markdown 非常适合写作，但 RST 为技术文档提供了强大的功能。通过将 Markdown 转换为 RST，您可以用 Markdown 快速编写，并与现有的 Python 文档工作流程集成。

为什么要转换为 RST？

Sphinx 兼容 - RST 是 Sphinx 的原生格式
Python 生态系统 - 大多数 Python 文档使用 RST
交叉引用 - RST 支持强大的文档间链接
扩展 - 访问 Sphinx 强大的扩展生态系统
Read the Docs - 与 RTD 托管直接集成

工作原理

当您将 Markdown 转换为 RST 时，会得到正确的 RST 语法：

Introduction
============

This is a paragraph with **bold** and *italic* text.

* First item
* Second item

Code Example
------------

.. code-block:: python

   def greet(name):
       return f"Hello, {name}!"

转换为 RST

Markdown 到 RST 的映射

Markdown	RST 输出
`# Heading`	用 `=====` 下划线
`## Subheading`	用 `-----` 下划线
`bold`	`bold`
`italic`	`italic`
`code`	``code``
`[text](url)`	`text <url>`_
代码块	`.. code-block::`

将 RST 与 Sphinx 配合使用

基本工作流程

用 Markdown 快速编写内容
使用 Markdown2ANY 转换为 RST
添加 RST 特有功能（指令、交叉引用）
使用 Sphinx 构建：sphinx-build -b html source/ build/

添加 RST 功能

转换后，使用 Sphinx 指令增强您的 RST：

.. note::
   This is a note admonition.

.. warning::
   This is a warning.

.. seealso::
   :doc:`other-document`

常见使用场景

API 文档

将 README 文件和指南转换为 RST，以便与自动生成的 API 参考文档集成。

教程

用 Markdown 编写教程，转换为 RST，然后添加到 API 文档的交叉引用。

贡献指南

创建与项目其余文档格式一致的贡献者文档。

RST 特有功能

转换后，您可以添加 Markdown 不支持的 RST 功能：

警告框 - 注意、警告、提示、危险框
交叉引用 - 文档和章节之间的链接
角色 - 语义标记如 :func:、:class:
指令 - 自定义内容块
目录树 - 文档层次结构