这些格式在twisted的文档字符串中是什么意思？ [英] What's meaning of these formats in twisted's docstring?

问题描述

在扭曲的源代码中，许多文档包含这样的格式：L {xxx}或C {xxx}或以'@'开头的行，它们的含义是什么？

<例如，在twisted / internet / interfaces.py中：

  def registerProducer（producer，streaming）：
 $b $ b注册接收生产者的数据
 ... 
对于L {IPullProducer}提供程序，每次需要数据时，C {resumeProducing}将被调用一次
 
 ... 
 @type producer：L {IProducer} provider 
 ... 
 @return：C {None} 

  

L {IPullProducer}，C {resumeProducing}，@type producer？

顺便说一下，这些格式是标准python文档字符串格式的一部分吗？如果是的话，我应该在哪里提及？感谢：）

解决方案

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

L {} 表示链接（即这是一个Python标识符，请链接到它） C { 表示代码（即 hello C {foo} bar 应格式化为hello foo ）。 I {} 只是表示斜体。您可以在epytext文档中看到更多字段。





Twisted项目使用 pydoctor --add-package twisted 这样的调用。还有一点，可以生成Twisted所依赖的其他项目的链接，但是如果您想为Twisted提供文档，则可以使用它来获得一个想法。你也可以用epydoc自己生成文档，使用 epydoc twisted ，但是epydoc不知道Zope接口，所以不会自动把类链接到它们实现的接口。

每个版本的生成API文档是发表在twistedmatrix.com ，你可以在那里浏览。

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?

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 ?

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

解决方案

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

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.

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.

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

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