imported>Requii：修饰语句，增加或调整内部链接

2025-01-14T15:15:43Z

修饰语句，增加或调整内部链接

新页面

{{Copy edit|time=2023-12-23T08:19:17+00:00}}
{{NoteTA|G1=IT}}
{{DISPLAYTITLE:reStructuredText}}
{{Infobox file format
| name = reStructuredText
| icon = [[File:ReStructuredText Logo.svg|frameless|reStructuredText logo]]
| iconcaption =
| screenshot =
| caption =
| extension = .rst
| mime = text/x-rst
| type_code =
| uniform_type =
| conforms_to =
| magic =
| developer = David Goodger
| type =
| released = {{Start date and age|2002|04|02}}
| latest_release_version = Revision 10002
| latest_release_date = {{Start date and age|2024|12|16}}
| container_for =
| contained_by =
| extended_from =
| extended_to =
| standard =
| free = [[Public domain]]
| url = {{URL|https://docutils.sourceforge.io/rst.html}}
}}

'''reStructuredText'''（'''RST'''、'''ReST'''或'''reST'''）是一种用于文本数据的文件格式，主要用于 [[Python]] 编程语言社区的技术文档。

它是 Python Doc-SIG（Documentation Special Interest Group）的 Docutils 项目的一部分，旨在为 Python 创建一组类似于 [[Java]] 的 [[Javadoc]] 或 [[Perl]] 的 Plain Old Documentation（pod）的工具。Docutils 可以从 Python 程序中提取注释和信息，并将它们格式化为各种形式的程序文档。<ref>{{Cite web|url=https://www.ibm.com/developerworks/library/x-matters24/|title=XML Matters: reStructuredText|accessdate=2016-10-05|author=Mertz|date=2003-02-01|first=David|publisher=[[IBM developerWorks]]|archive-date=2016-10-06|archive-url=https://web.archive.org/web/20161006050425/https://www.ibm.com/developerworks/library/x-matters24/|dead-url=no}}</ref>

从这个意义上说，reStructuredText 是一种轻量级[[标记语言]]，其设计目的是令文档处理软件（如 Docutils）可以处理它，同时使会读写 Python 源代码的程序员也容易读它。

== 历史 ==
早期的轻量级标记语言 StructuredText（由 Zope 开发）存在许多问题，reST 就是为了解决这些问题而开发的。<ref>{{Cite web|url=http://docutils.sourceforge.net/rst.html|title=reStructuredText: Markup Syntax and Parser Component of Docutils|accessdate=2016-10-05|author=Goodger|date=2016-05-24|first=David|publisher=Docutils Project|archive-date=2016-10-05|archive-url=https://web.archive.org/web/20161005021246/http://docutils.sourceforge.net/rst.html|dead-url=no}}</ref>选择了 reStructuredText 这个名称是为了表明 reST 是一个“经过修改、重写和重新解释的结构化文本”。<ref>{{Cite web|url=http://docutils.sourceforge.net/FAQ.html#why-is-it-called-restructuredtext|title=Docutils FAQ (Frequently Asked Questions)|accessdate=2016-10-05|author=Goodger|date=2016-02-26|first=David|publisher=Docutils Project|archive-date=2016-09-30|archive-url=https://web.archive.org/web/20160930115647/http://docutils.sourceforge.net/FAQ.html#why-is-it-called-restructuredtext|dead-url=no}}</ref>

reST 在 2002 年开始在 Python 社区中得到了重要的应用。

== 参考实现 ==
reST 解析器的引用实现是 Python 编程语言中的 Docutils 文本处理框架的一个组件，但是还可以使用其他解析器。

Docutils 项目没有正式将 [[MIME]] 类型注册为 reStructuredText，但实际上有在使用<code>text/x-rst</code>。<ref>{{Cite web|url=http://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data|title=What's the official MIME type for reStructuredText data? in Docutils FAQ.|accessdate=2017-12-20|publisher=Docutils Project|archive-date=2017-12-10|archive-url=https://web.archive.org/web/20171210145233/http://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data|dead-url=no}}</ref>

== 应用程序 ==
reStructuredText 通常用于技术文档，例如 Python 库的文档。<ref>{{Cite web|url=https://www.python.org/dev/peps/pep-0287/|title=PEP 287 -- reStructuredText Docstring Format|accessdate=2016-10-05|author=Goodger|date=2002-04-02|first=David|publisher=[[Python Software Foundation]]|archive-date=2016-10-06|archive-url=https://web.archive.org/web/20161006060009/https://www.python.org/dev/peps/pep-0287/|dead-url=no}}</ref>然而，它也适用于广泛的文本。

自 2008 年以来，reST 一直是 Python 的 Sphinx 文档生成系统的核心组件。

[[Trac]] 也支持 reStructuredText，[[GitHub]] 和 [[Bitbucket]] 也是如此。<ref>{{Cite web|url=https://trac.edgewall.org/wiki/WikiRestructuredText|title=reStructuredText Support in Trac|accessdate=2016-10-05|date=2016-09-13|publisher=[[Trac]]|archive-date=2016-10-06|archive-url=https://web.archive.org/web/20161006053055/https://trac.edgewall.org/wiki/WikiRestructuredText|dead-url=no}}</ref>

为古登堡计划准备文本的分布式校对器正在考虑采用 reST 作为一种基本格式，其他电子书格式可以从这种格式生成。<ref>{{Cite web|url=http://www.pgdp.net/phpBB2/viewtopic.php?t=44456|title=Minutes of 2010 December 11 meeting|accessdate=2011-01-08|author=Newby|date=2011-01-08|first=Greg|publisher=Distributed Proofreaders}}</ref>

2016 年 7 月，Linux 内核项目决定从基于 [[DocBook]] 的文档过渡到 reStructuredText 和 Sphinx 工具链。<ref>{{Cite web|url=http://lwn.net/Articles/692704/|title=Kernel documentation with Sphinx, part 1: how we got here|accessdate=2016-10-27|date=2016-07-06|publisher=LWN.net|archive-date=2016-10-25|archive-url=https://web.archive.org/web/20161025063027/https://lwn.net/Articles/692704/|dead-url=no}}</ref>

在 3.0 版本中，软件构建工具 [[CMake]] 从自定义标记语言转换为 reStructuredText。<ref>{{Cite web|url=https://cmake.org/cmake/help/v3.0/release/3.0.0.html|title=CMake 3.0.0 Release Notes|accessdate=2016-10-05|date=2014-06-10|publisher=Kitware, Inc.|archive-date=2016-12-02|archive-url=https://web.archive.org/web/20161202052556/https://cmake.org/cmake/help/v3.0/release/3.0.0.html|dead-url=no}}</ref>

== reST标记示例 ==

=== 标题 ===
节标题
<nowiki>==============</nowiki>

小节标题
------------------

=== 列表 ===
<syntaxhighlight lang="restructuredtext">
- 列表条目
- 另一个列表条目

- 子列表条目

- 列表之间空行以分隔条目

* 改变条目标点以分割列表

- 又一个条目

1) 编号列表条目

2) 另一条

a) 一个很长很长的列表条目，这条的内容太长了以至于\
要换行书写。注意换行时左侧要对齐文本，而不是编\
号。行末加反斜杠可避免在中文之间空格。

i) 列表里面甚至还可以

分段。

3) 第三条

#) 又一个条目

#) 再一个条目
</syntaxhighlight>

=== 图片 ===
<syntaxhighlight lang="restructuredtext">
.. image:: /path/to/image.jpg
</syntaxhighlight>

=== 指定链接 ===
<syntaxhighlight lang="restructuredtext">
链接到\ `维基百科`_\ 和\ `Linux 内核存档`_\ 。汉字与格式标志之间插入反斜杠和空格以进行分隔。

.. _维基百科: https://www.wikipedia.org/
.. _Linux 内核存档: https://www.kernel.org/
</syntaxhighlight>

=== 匿名链接 ===
<syntaxhighlight lang="restructuredtext">
这句话可以\ `匿名链接到 Python 网站`__。

__ https://www.python.org/
</syntaxhighlight>N.B.: 指定链接和匿名链接用重字符(`)括起来，而不是用引号(')括起来。

=== 文字块 ===
<syntaxhighlight lang="restructuredtext">
::

Literal 文本

在段落最后也可以插入 Literal 文本标志符::

又一段 Literal 文本

.. code:: python

print("一段明示为 Python 语言代码的 Literal 文本")
</syntaxhighlight>

== 另请参阅 ==

* [[文档标记语言比较]]
* {{link-en|文档生成器比较|Comparison of documentation generators}}
* {{link-en|笔记软件比较|Comparison of notetaking software}}

== 参考文献 ==
<references responsive=""></references>

== 外部链接 ==

* [http://docutils.sourceforge.net/rst.html reStructuredText官方网站，附有参考页面]{{Wayback|url=http://docutils.sourceforge.net/rst.html |date=20181201141327 }}

{{Document markup languages}}

[[Category:轻量级标记语言]]
[[Category:有未审阅翻译的页面]]

ReStructuredText - 版本历史

imported>Requii：​修饰语句，增加或调整内部链接

imported>Requii：修饰语句，增加或调整内部链接