---

📄 项目文档写作规范指南

本指南适用于使用 Sphinx 构建的文档项目，主要介绍 .rst 文件的编写规范和最佳实践，帮助团队统一文档风格，提高可读性和可维护性。

---

目录

1. 文档结构控制 (index.rst)
2. 标题与段落
3. 列表
4. 超链接
5. 图片插入
6. 注释
7. 代码块
8. 表格
9. 完整示例模板

---

1. 文档结构控制 (index.rst)

• 使用 .. toctree:: 指令组织文档目录结构。

• 推荐设置 :maxdepth: 2，避免嵌套层级过深。

• 子页面按逻辑顺序排列，例如：

  介绍 → 安装 → 使用 → API 文档 → 贡献指南 → FAQ → 更新日志
  

• 每个子页面对应一个 .rst 文件（如：introduction.rst, installation.rst），引用时无需添加 .rst 后缀。

示例：

.. toctree::
   :maxdepth: 2

   introduction
   installation
   usage

---

2. 标题与段落

标题层级符号推荐顺序：

层级	符号
一级标题	=
二级标题	-
三级标题	^
四级标题	'

⚠️ 注意：标题必须有下划线；若需上下都加相同符号，则表示独立章节。

段落格式：

• 多行连续文本组成一个段落。
• 不同段落之间用空行分隔。

---

3. 列表

无序列表

使用 *、- 或 + 开头表示项目符号：

- 第一项
* 第二项
+ 第三项

有序列表

使用数字加句点开头表示有序项：

1. 第一步
2. 第二步

---

4. 超链接

内部链接

使用反引号加下划线定义引用链接：

请查看 `安装说明`_。

.. _安装说明: installation

外部链接

将 URL 放入尖括号中，并在反引号内写入显示文字：

访问 `官方网站 <https://example.com>`_。

---

5. 图片插入

使用 .. image:: 指令插入图片，并可设置属性：

.. image:: /path/to/image.png
   :width: 200px
   :alt: 替代文字

---

6. 注释

单行注释以两个点加空格开头：

.. 这是一个注释，不会出现在生成的文档中。

---

7. 代码块

使用 .. code-block:: 指令插入代码块，并指定语言类型以启用语法高亮：

.. code-block:: python

   def hello():
       print("Hello, world!")

---

8. 表格

使用等号和竖线创建简单表格：

=====  =====
列 A    列 B
=====  =====
1      2
3      4
=====  =====

---

9. 完整示例模板（index.rst）

My Project Documentation
========================

欢迎阅读本项目的文档。您可以在这里找到使用方法、API 说明以及贡献指南。

Contents:

.. toctree::
   :maxdepth: 2

   introduction
   installation
   usage
   api
   contributing
   faq
   changelog

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

---