Question

看起来sphinx.ext.autodoc已经成为Python文档字符串中＆＃34; JavaDoc＆＃34;类评论的事实标准。

Sphinx用于在docs.python.org上生成文档。但它是否从Python源.py文件（使用autodoc）读取文档字符串以显示在docs.python.org上？

library section of the docs包含逐个方法的摘要，但这些摘要与文本无关。他们是否与源代码中的评论保持同步？

换句话说，是否有一个地方可以在文档中找到完全相同的文本（格式化旁边），以及从解释器查询文档字符串？

我还没能找到这样的地方。例如，使用帮助机制查看用于打印的docstring会产生：

>>> help(print)
Help on built-in function print in module builtins:
print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

当我在3.6.2文档（与上面使用的版本相同）中查找打印时，我发现different documentation for print没有任何参数参数说明：

print（* objects，sep =''，end ='\ n'，file = sys.stdout，flush = False）

打印   对象到文本流文件，由sep分隔，后跟end。   sep，end，file和flush（如果存在）必须以关键字形式给出   参数。

所有非关键字参数都转换为字符串，如str（）和   写入流，由sep分隔，然后结束。两个sep   并且必须是字符串;它们也可以是None，这意味着使用   默认值。如果没有给出对象，print（）将只写入结束。

file参数必须是带有write（string）方法的对象;如果它   不存在或无，将使用sys.stdout。自印刷   参数转换为文本字符串，print（）不能与之一起使用   二进制模式文件对象。对于这些，请改用file.write（...）。

输出是否缓冲通常由文件确定，但如果是   flush关键字参数为true，强制刷新流。

版本3.3中已更改：添加了flush关键字参数。

Answer 1

检查conf.py file for the Python docs，autodoc扩展没有配置。这些文档不使用autodoc或从源代码文档字符串中读取。

Answer 2

文档不是从Python源代码生成的。您可以在存储库中的Docs文件夹下看到.rst个文件。

Docstrings是分开的。文档字符串不用于生成文档，您也不会在文档中找到文档字符串。

docs.python.org使用sphinx.ext.autodoc吗？

2 个答案: