ulif.rest 0.1.0

先决条件

您需要

• Python 2.4。据说Python 2.5也可以。

• setuptools，可以从http://peak.telecommunity.com/DevCenter/setuptools获得

其他所需的软件包将在安装过程中下载。因此，您需要在安装过程中连接到互联网。

安装

通常，此软件包应从使用它作为辅助库的其他软件包中获取。因此，您无需关心安装。如果要将ulif.rest集成到您的项目中，只需在您的setup.py中声明ulif.rest为所需软件包即可。

$ python2.4 bootstrap/bootstrap.py

$ bin/buildout

$ bin/test

# easy_install ulif.rest

用法

请参阅 README.txt 和 src/ulif/rest/ 目录中的其他 .txt 文件，以获取 API 文档。

这是什么？

此软件包中收集的扩展提供对 Python 文档工具链中 RestructuredText 文档使用的某些标记语言的支持。

RestructuredText 是一种具有特殊人类可读标记的文档标记语言，在 Python 界中得到广泛应用。RestructuredText 文档有点像 HTML，但可读性更好。您正在阅读的文本，例如，就是用 ReST 编写的。

查看：

http://docutils.sourceforge.net/rst.html

了解有关 ReST（以及 docutils）的更多信息。

通常，ReST 文档可以使用 Python 软件包 docutils 中的工具进行处理。该 docutils 包含读取器、解析器、编写器和发布者，用于读取 ReST 文档并写入各种输出格式，如 HTML、XML 或 LaTeX。

由于 Python 从 2.6 版本开始使用 ReST 文档代替 LaTeX，因此引入了一些特殊标记，如 function、seealso 或 versionchanged，这有助于更精确地描述编程 API。然而，这些附加“标签”需要专门的读取器、解析器、编写器和发布者才能理解。正常的 docutils 工具不理解这些新角色和指令。

此软件包使得可以使用以下列出的附加角色/指令的 docutils 解析器和编写器。

先决条件和要求

• docutils – 推荐版本为 0.4。

  可以从 http://docutils.sourceforge.net/ 获取。

• Pygments – 一种语法高亮工具。

  可以从 https://pygments.pythonlang.cn/ 获取。如果您想在 ReST 文档中对代码片段进行语法高亮，则需要此工具。

  由于目前仅支持 HTML 使用 pygments，因此您不需要使用它来处理其他输出格式。在这种情况下，您不需要 pygments。

这两个软件包也可以通过 cheeseshop 和 easy_install 获取。

激活对附加角色/指令集的支持

只需导入此软件包中的模块

from ulif.rest import directives_plain
from ulif.rest import roles_plain
from ulif.rest import pygments_directive # for syntax-highlighting support

就这样。模块会自动定义和注册新的角色和指令与 docutils。您不需要调用特殊函数。

运行测试

使用您喜欢的 Python 解释器调用 tests/alltests.py

$ python tests/alltests.py

注意，docutils 必须在您的 PYTHON_PATH 中可用。

如果您使用 buildout 安装了源版本（而不是 egg），您可以在源根目录的 bin/ 目录中生成一个 buildout 可执行文件并运行

$ bin/test

支持哪些角色和指令

pygments_directive 添加以下新指令

• sourcecode – 用于高亮显示以下内容的指令

  代码块。它接受一个参数，即语言，目前仅支持HTML输出。

  示例

  .. sourcecode:: python
  
     class Cave(object):
          pass
  
  This will render the class definition with
  colours.
  
  An additional optional parameter is ``linenos``,
  which adds linenumbers to the code::
  
  .. sourcecode:: python
     :linenos:
  
     class NumberedCave(object):
         pass
  
  will render the code block with line numbering.
  
  See the source for further options.

• code-block – sourcecode的别名。

directives_plain 增加了以下新指令

• function – 用于描述带有签名的函数的指令。

  签名。

• data – ???

• class – 用于定义Python类的指令。

• method – 用于描述Python类方法的指令。

• attribute – 用于描述Python类属性的指令。

  类。

• exception – 用于描述异常的指令。

• cmdoption – 用于描述命令选项的指令。

• envvar – 用于描述环境变量的指令。

• describe – 用于描述某物的指令。

• seealso – 用于添加“另见”子节的指令。它需要一个“正文”文本。

  。

• deprecated – 用于添加弃用警告的指令。它也需要一些解释性正文和一个版本号。

  。

• versionadded – 用于添加一条注释，说明在哪个版本中将周围的内容添加到API中。

  需要版本号和解释性文本。

  versionchanged – 用于添加一条注释，说明在哪个版本中签名或其他内容发生了变化以及原因。

  示例

  .. versionadded:: 0.11
  
     Added for convenience reasons.

• 。

  toctree – 请求根据指令正文部分中给出的文件生成目录树表的指令。所谓的目录树将不会由标准编写器生成，因为它需要至少两次解析（一次收集所有引用，另一次生成引用目标）。

  示例

  .. versionchanged:: 0.11
  
    Added cave parameter, because every caveman
    needs a cave.

• 。

  如果你在文档中插入toctree指令，这不会阻止文档的解析，但生成的目录树在渲染文档中将“不可见”。

  toctree指令支持一个maxdepth参数，它是一个数字，告诉要生成到哪个深度的目录树（默认：无限制）。

  。

  示例

  .. toctree::
     :maxdepth: 2
  
     chapter1.rst
     chapter2.rst
     another_file.rst
  
  This should render a table of contents with the
  headings of the three given files. Only headers of
  level 1 and 2 will be included in the toctree.

roles_plain 增加了以下新角色

• data

• exc

• func

• class

• const

• attr

• meth

• cfunc

• cdata

• ctype

• cmacro

• mod

• keyword

• ref

• token

• term

• file

• samp

每个角色都可以像这样使用：<rolename>:<text>。例如

:func:`my_function`

将输出文本my_function，以不同于普通文本的方式渲染。确切的渲染方式取决于使用的编写器和翻译器。在通常的HTML编写器中，它将以罗马字体渲染。

所有其他角色也是如此。

功能变更

• 初始发布