Python 中文
Space shortcuts
Page tree
Skip to end of metadata
Go to start of metadata

中文标题【reStructuredText】

"reStructuredText" 是一个词，不是 2 个词！


本文档是基于官方 reStructuredText 进行重新处理

官方的文档和工具地址为：https://docutils.sourceforge.io/。

如果你希望对官方的文档进行重新构建编译生成你需要的 HTML 文件的话，你可以使用 Python 的命令进行处理，构建的方法请参考页面：https://www.ossez.com/t/python-docutils/185 中的内容。



reStructuredText 是一个易于阅读，所见即所得的纯文本标记句法（markup syntax）和处理系统。通常 reStructuredText 被用来内联程序（in-line program）的文档 ，例如 Python 的文档字符，或者被用来创建简单的 Web 页面或者独立的文档。

reStructuredText 被设计用来针对特定的应用领域。 reStructuredText 处理程序是 Docutils 的一个组件。reStructuredText 是 StructuredText 和 Setext 修改和重新解释的轻量标记系统（markup systems）。

reStructuredText 的主要目的是针对 Python 文档系统和其他文档域的标记语法实现，能够保证可读和简单，能够保证足够强大的文档能力，避免不需要的功能。Markup 使用的目的是将 reStructuredText 文档转换可用的其他数据结构格式。

请参考 statemachine.py 来查看 Python 的示例模块，其中演示了使用 reStructuredText 的完整情况。

reStructuredText 用户文档

Users who have questions or need assistance with Docutils or reStructuredText should post a message to the Docutils-users mailing list.

reStructuredText 参考文档


Developer Documentation


How-To's

Try it Online

If you want to try reStructuredText out without downloading Docutils, you can play with the "simple online editor for reStructuredText" on http://rst.ninjs.org/

Testimonials

The following testimonials are excerpts from unsolicited posts to mailing lists and the comp.lang.python newsgroup. Being excerpts, there's often context missing, which sometimes tones down the message.

Ueli Schlaepfer on Doc-SIG, 2002-03-28:

I have adopted reST as my tool of choice for producing notes while doing lab work (mostly in a matlab environment). Since then, the quality of such documentation has increased noticeably, mostly for two reasons:

  • I no longer need to switch to another tool, so the threshold has fallen to very low. Note that "another tool" means Winword...
  • Still, I have a powerful set of markup constructs at my fingertips that let me create the kind of documents I need with more ease than any other tool I can think of.

Thanks to reST/DPS [now Docutils --ed], I'll soon be able to go ahead and apply the same tools for extracting documentation out of my Python code. Hey, that's a printable and a browsable version for free! Personally, I consider this a large benefit.

... All essential constructs for everyday use are there, and much more if needed. ...

Guido van Rossum, enthusiastic about PEP 287 but a bit hasty (see the follow-ups) on Python-Dev, 2002-04-02:

Good PEP, David! What's the next step? Should the processing code be incorporated in the standard library? Should we start converting the standard library docs to reStructuredText?

Timothy Delaney on comp.lang.python, 2002-04-03:

I read through all the reStructuredText docs, comparing the text versions to the html versions. I found the text versions to be very easy to read, whilst making it obvious in most cases when something was "special".

I particularly like the system of doing hyperlinks...

Definitely +1 from me ... I would really like a standard, clean docstring format. Might make it easier to get my next project done in Python...

Guido van Rossum on Python-Dev, 2002-04-03:

I think that reStructuredText is a good format for marking up docstrings; it's probably as good as it gets given the requirements (a fairly elaborate feature set, yet more readable "in the raw" than HTML).

Richard Jones on comp.lang.python, 2002-04-03:

How I see it is that ReST is a middle ground between markup and non-. It has markup, and you can use it to the extreme. Or you can follow some simple conventions (the most basic form of markup) and not worry about all the finer detail stuff. The difference between:

@section{The Section Title}

and:

The Section Title
-----------------

Is pretty clearly to me that the second doesn't look like markup, even though it is.

Guido van Rossum on Python-Dev, 2002-04-04:

Structured text is really a great idea for certain situations; reST is a much better implementation of the idea than any versions I've seen before.

Max M on comp.lang.python, 2002-04-05:

Any programmer can learn the basics in 15 minutes or less.

And it really is very very easy to write documents in it. I do belive that if I were ever to write a book (again) I would write it in ReST.

And as far as I can tell from the specs, ReST solves most of the problems I have had with structured text. A few things gets a little more complicated and some get simpler. All in all a good bargain.

I would certainly use it. I also hope that it gets integrated into Zope.

David Abrahams on Python-Dev, 2002-04-06:

Incidentally, I'm really excited about reST. I've been looking for a tolerable markup for C++ comments, and reST looks like it might fit the bill.

Eric Jones on Python-Dev, 2002-08-01:

I would very much like to see reStructuredText, or some minor variation on it, move forward as a "standard" for doc-strings very soon. I have long lamented not having a prescribed format and an associated processing tool suite included in the standard library. Even if the format isn't perfect (I think it looks very good), it is time to pick a reasonable candidate and go.

This being the Internet, there were plenty of people opposed to the idea of reStructuredText, some vehemently. Discovering those gems is left as an exercise for the reader.

  • No labels