我在Python中看到过几种不同的写作文档字符样式,是官方还是"同意"的风格？
有没有一种机制可以注释掉大块的Python代码？
现在,我能看到注释掉代码的唯一方法是用a开始每一行#,或用三引号括起代码:""".
这些问题是#在每行之前插入很麻烦,"""并使我想用作注释的字符串显示在生成的文档中.
阅读完所有评论后,答案似乎是"不".
我目前从Python开始,我有一个强大的PHP背景,在PHP中我习惯使用javadoc作为文档模板.
我想知道它是否javadoc有它作为docstringPython文档的位置.这里有既定的惯例和/或官方的guildelines？
例如,这样的东西太精巧,不适合Python的思维方式,或者我应该尽量简洁？
"""
replaces template place holder with values
@param string timestamp formatted date to display
@param string priority priority number
@param string priority_name priority name
@param string message message to display
@return string formatted string
"""
如果我有点过于详尽,我应该选择这样的东西(大多数文档不通过该__doc__方法打印)？
# replaces template place holder with values
#
# @param string timestamp formatted date to display
# @param string priority priority number
# @param string priority_name priority name
# @param string message …我正在编写一个轻量级类,其属性旨在可公开访问,并且有时仅在特定实例中被覆盖.在Python语言中没有为类属性或任何类型的属性创建文档字符串的规定.记录这些属性的可接受方式是什么？目前我正在做这样的事情:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Attributes:
"""
flight_speed = 691
__doc__ += """
flight_speed (691)
The maximum speed that such a bird can attain.
"""
nesting_grounds = "Raymond Luxury-Yacht"
__doc__ += """
nesting_grounds ("Raymond Luxury-Yacht")
The locale where these birds congregate to reproduce.
"""
def __init__(self, **keyargs):
"""Initialize the Albatross from the keyword arguments."""
self.__dict__.update(keyargs)
这将导致类的docstring包含初始标准docstring部分,以及通过扩充赋值为每个属性添加的行__doc__.
虽然在文档字符串样式指南中似乎没有明确禁止这种样式,但它也没有作为选项提及.这里的优点是它提供了一种方法来记录属性及其定义,同时仍然创建一个可呈现的类docstring,并避免编写重复来自docstring的信息的注释.我仍然有点生气,我必须实际写两次属性; 我正在考虑使用docstring中值的字符串表示来至少避免重复默认值.
这是否是对特设社区公约的毁灭性违反？好吗？有没有更好的办法？例如,可以创建包含属性值和文档字符串的字典,然后__dict__在类声明的末尾将内容添加到类和docstring中; 这样可以减少两次输入属性名称和值的需要. 编辑:我认为,这最后一个想法实际上是不可能的,至少不是没有从数据动态构建整个类,这似乎是一个非常糟糕的想法,除非有其他理由这样做. …
我喜欢doxygen来创建C或PHP代码的文档.我有一个即将推出的Python项目,我想我记得Python没有/* .. */评论,并且还有自己的自我文档工具,这似乎是pythonic的文档方式.
由于我熟悉doxygen,我如何使用它来生成我的Python文档？有什么特别需要注意的吗？
是否可以以简单的方式将文档字符串添加到namedtuple？
我试过了
from collections import namedtuple
Point = namedtuple("Point", ["x", "y"])
"""
A point in 2D space
"""
# Yet another test
"""
A(nother) point in 2D space
"""
Point2 = namedtuple("Point2", ["x", "y"])
print Point.__doc__ # -> "Point(x, y)"
print Point2.__doc__ # -> "Point2(x, y)"
但这并没有削减它.是否有可能以其他方式做？
我有一个带有docstring的Python脚本.当解析命令行参数不成功时,我想打印文档字符串以获取用户的信息.
有没有办法做到这一点？
#!/usr/bin/env python
"""
Usage: script.py
This describes the script.
"""
import sys
if len(sys.argv) < 2:
print("<here comes the docstring>")
PyCharm 2.7(或PyCharm 3)是否支持自定义docstring和doctest存根？如果是这样,如何编写这种特定类型的自定义扩展？
我目前的项目已经标准化使用Google Python样式指南(http://google-styleguide.googlecode.com/svn/trunk/pyguide.html).我喜欢PyCharm的docstring支持,但现在只有两种支持的格式是epytext和reStructureText.我想并且愿意自己写一个PyCharm插件,它创建一个以Google或Numpydoc风格格式化的文档注释存根(https://pypi.python.org/pypi/sphinxcontrib-napoleon/).这里特别重要的是结合PyCharm与其他两种文档类型的类型推断能力.
我想从函数本身内部打印python函数的docstring.例如.
def my_function(self):
"""Doc string for my function."""
# print the Docstring here.
目前我my_function在定义之后直接这样做.
print my_function.__doc__
但宁愿让函数自己这样做.
我已经打过电话print self.__doc__ print self.my_function.__doc__和print this.__doc__内部创建my_function但这并没有工作.
我很快就开始了一个开源Python项目,我正在尝试提前决定如何编写我的文档字符串.显而易见的答案是使用reStructuredText和Sphinx与autodoc,因为我真的喜欢简单地在我的文档字符串中正确记录我的代码然后让Sphinx为我自动构建API文档.
问题是它使用的reStructuredText语法 - 我认为它在呈现之前是完全不可读的.例如:
:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File instance
is destructed
:type temporary: bool
你必须真正放慢脚步,花一点时间才能理解这种语法混乱.我更喜欢谷歌方式(谷歌Python风格指南),与上面的对应方式如下:
Args:
path (str): The path of the file to wrap
field_storage (FileStorage): The FileStorage instance to wrap
temporary (bool): Whether or not to delete the file when the File … python documentation restructuredtext docstring python-sphinx