扭曲的文档字符串中这些格式的含义是什么? [英] What's meaning of these formats in twisted's docstring?

问题描述

在twisted的源代码中，很多文档字符串包含这样的格式:L{xxx}或C{xxx}或以'@'开头的行，它们的含义是什么?

In twisted's sourcecode, many docstrings contain formats like this: L{xxx} or C{xxx} or a line begin with an '@', what's their meanings?

例如，在twisted/internet/interfaces.py中:

for example, in twisted/internet/interfaces.py:

def registerProducer(producer, streaming):
    """
    Register to receive data from a producer.
    ...
    For L{IPullProducer} providers, C{resumeProducing} will be called once
    each time data is required.
    ...
    @type producer: L{IProducer} provider
    ...
    @return: C{None}
    """

L{IPullProducer} , C{resumeProducing} , @type producer ?

顺便问一下，这些格式是标准 python 文档字符串格式的一部分吗?如果是这样，我应该参考哪里?谢谢:)

By the way, are these formats a part of standard python docstring formats? If so, where should I refer to? Thanks :)

推荐答案

Twisted 使用的文档格式是 Epytext，记录在 epydoc.sourceforge.net 上.

The documentation format used by Twisted is Epytext, which is documented on epydoc.sourceforge.net.

L{} 表示链接"(即这是一个 Python 标识符，请链接到它") C{} 表示代码"(即 hello C{foo} bar 的格式应类似于hello foo bar").I{} 仅表示斜体".您可以在 epytext 文档中看到更多字段.

L{} means "link" (i.e. "this is a Python identifier, please link to it") C{} means "code" (i.e. hello C{foo} bar should be formatted like "hello foo bar"). I{} just means "in italics". You can see more fields in the epytext documentation.

Twisted 项目使用 pydoctor 生成其文档，使用像 pydoctor --add-package 这样的调用扭曲.它还有更多内容，可以生成指向 Twisted 所依赖的其他几个项目的链接，但如果你想向 Twisted 贡献文档字符串，你可以使用它来获得一个想法.您也可以使用 epydoc 本身生成文档，使用 epydoc twisted，但 epydoc 不了解 Zope 接口，因此不会自动将类链接到它们实现的接口.

The Twisted project generates its documentation with pydoctor, using an invocation like pydoctor --add-package twisted. There's a little more to it, to generate links to a couple of other projects that Twisted relies upon, but you can use that to get an idea if you want to contribute docstrings to Twisted. You can also generate the documentation with epydoc itself, using epydoc twisted, but epydoc doesn't know about Zope Interface and so won't automatically link classes to the interfaces that they implement.

为每个版本生成的 API 文档发布在 twistedmatrix.com，您可以在那里浏览它.

The generated API documentation for each release is published on twistedmatrix.com, and you can browse it there.

这篇关于扭曲的文档字符串中这些格式的含义是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！