So I've gotten somewhat used to Javadoc style documentation. Looking through various examples of Python code, I'm finding that, at first blush, the documentation seems to be missing a lot of information.
所以我有点习惯了Javadoc风格的文档。通过查看各种Python代码示例，我发现，乍一看，文档似乎缺少很多信息。
The good: vary rarely do you see self-evident bits of documentation. Docstrings are usually a paragraph or less of English markup that integrates instead of standing out on separate lines.
好处:变化很少会出现不证自明的文档。docstring通常是一段或更少的英语标记，它集成而不是单独的行。
The bad: in conjunction with Python's duck-typing, I find that many functions are unclear about the parameters they expect. There's no type hinting (duck-hinting?) and often times it would be nice to have some idea that the parameter should be list-like, string-like, stream-like.
缺点:结合Python的duck-typing，我发现很多函数都不清楚它们期望的参数。不存在类型暗示(duck-hinting?)，而且通常情况下，如果能知道参数应该是类似于列表的、类似字符串的、类似于流的，那就更好了。
Of course, Javadoc was designed for a lower-level language, without great introspection abilities of Python, which might account for the less verbose documentation philosophy.
当然，Javadoc是为一种低级语言而设计的，没有Python的强大的内省能力，这可能解释了较不冗长的文档哲学。
Any advice on Python documentation standards and best-practices?
关于Python文档标准和最佳实践有什么建议吗?
1 个解决方案
#1
9
The reStructuredText format was designed in response to the need for Python documentation that could be embedded in docstrings, so the best thing is to learn reST and format your docstrings with that format. You might find, as I did, that you then go on to format just about any documentation in reST, but that's a side point :-)
streamlined turedtext格式是为了响应Python文档的需要而设计的，这些文档可以嵌入到docstring中，所以最好的事情是学习reST并用这种格式格式化您的docstring。您可能会发现，就像我所做的那样，您将继续格式化任何其他文档，但这是一个侧重点:-)
For specifically documenting your Python code, the Sphinx system is a set of extensions to the reST format, and a build system for rendering documents. Since it was designed to document Python itself, including the standard library, Sphinx allows for very well-structured documentation of source code, including of course the specifics of function signatures as you're asking. It allows a comprehensive documentation suite to be built, both auto-extracted and hand-written, all using the same formatting system.
对于特定的Python代码文档化，Sphinx系统是对reST格式的一组扩展，以及用于呈现文档的构建系统。由于它是设计用来记录Python本身的，包括标准库，Sphinx允许非常结构化的源代码文档，当然也包括函数签名的细节。它允许使用相同的格式化系统自动提取和手工编写一个完整的文档集。
If you only want documentation generated from your source code, then Epydoc will extract API documentation from your source code; it, too, reads reST formatting for the text.
如果您只想从源代码生成文档，那么Epydoc将从源代码中提取API文档;它也读取文本的reST格式。
#1
9
The reStructuredText format was designed in response to the need for Python documentation that could be embedded in docstrings, so the best thing is to learn reST and format your docstrings with that format. You might find, as I did, that you then go on to format just about any documentation in reST, but that's a side point :-)
streamlined turedtext格式是为了响应Python文档的需要而设计的，这些文档可以嵌入到docstring中，所以最好的事情是学习reST并用这种格式格式化您的docstring。您可能会发现，就像我所做的那样，您将继续格式化任何其他文档，但这是一个侧重点:-)
For specifically documenting your Python code, the Sphinx system is a set of extensions to the reST format, and a build system for rendering documents. Since it was designed to document Python itself, including the standard library, Sphinx allows for very well-structured documentation of source code, including of course the specifics of function signatures as you're asking. It allows a comprehensive documentation suite to be built, both auto-extracted and hand-written, all using the same formatting system.
对于特定的Python代码文档化，Sphinx系统是对reST格式的一组扩展，以及用于呈现文档的构建系统。由于它是设计用来记录Python本身的，包括标准库，Sphinx允许非常结构化的源代码文档，当然也包括函数签名的细节。它允许使用相同的格式化系统自动提取和手工编写一个完整的文档集。
If you only want documentation generated from your source code, then Epydoc will extract API documentation from your source code; it, too, reads reST formatting for the text.
如果您只想从源代码生成文档，那么Epydoc将从源代码中提取API文档;它也读取文本的reST格式。