标签: docstring

当您键入以下内容时,有没有办法让IPython完全呈现reStructuredText(对于Sphinx)文档字符串:

help foo

要么:

foo?

我觉得超级分心,试图读取IPython的帮助文档时,它显示了原始标记.reST非常适合Sphinx文档,但真正使简单的帮助查找变得混乱.我不能孤身一人......？

谷歌一直没有帮助.

我正在为我编写的软件包添加一些(epydoc)文档,而且我遇到了很多我多次重复自己的实例.

def script_running(self, script):
    """Return if script is running

    @param script: Script to check whether running

    @return: B{True} if script is running, B{False} otherwise
    @rtype: C{bool}
    """

PEP257说:

单行是非常明显的案例.

并且

函数或方法的docstring应该总结其行为并记录其参数,返回值,副作用,引发的异常以及何时可以调用它们的限制(如果适用,则全部).

在一行(描述)和完整的参数/返回字段之间画线的时候是否有一般的指导或标准做法？

或者在生成文档时,我应该为每个函数包含每个适用的字段,而不管它看起来多么重复？

奖金问题:从语法上讲,描述script参数的最佳方式是什么？

关于在Python类继承中继承docstrings有一个问题,但是那里的答案涉及方法docstrings.

我的问题是如何继承父类的docstring作为__doc__属性.用例是Django rest框架根据你的视图类的docstrings在你的API的html版本中生成了很好的文档.但是当在没有docstring的类中继承基类(带有docstring)时,API不会显示docstring.

很可能sphinx和其他工具做正确的事情并为我处理docstring继承,但django rest框架查看(empty).__doc__属性.

class ParentWithDocstring(object):
    """Parent docstring"""
    pass


class SubClassWithoutDoctring(ParentWithDocstring):
    pass


parent = ParentWithDocstring()
print parent.__doc__  # Prints "Parent docstring".
subclass = SubClassWithoutDoctring()
print subclass.__doc__  # Prints "None"

我尝试了类似的东西super(SubClassWithoutDocstring, self).__doc__,但这也只是让我了None.

在docstring中表达关键字参数的预期类型的​​传统方法是什么？

或者这是否是我不应该做的事情的原则？谷歌在这个问题上毫不怀疑.

(我感兴趣的是因为我发现跟踪所有变量的预期类型非常有用,因为我编码.我使用PyCharm,当参数有意外类型时,或者当自定义类属性可能未解决时,它会发出警告)

但是,我发现有时可能的keywrord参数列表列为

def foo(bar, parameter_1: int=1, paramter_2: str='', ...etc )

会变得漫长而难以理解..

请考虑以下代码

class Person:
    def __init__(self, id: int, **kwargs):
        """
        :param id: social security number
        :type id: int
        :param **name: person's first name
        :type **name: str
        :param **age: person's age in years, rounded down
        :type **age: int
        """
        self.data = kwargs


bob = Person(123456568, name='Bob', age=48)
sally = Person(1245654568, name='Sally', age='22')

我想使用docstring来声明预期的类型.而且我希望PyCharm警告我,莎莉的年龄是错误的.当然,我不知道PyCharm是否有能力"理解"文档字符串中的详细程度.不过我想知道传统方法是做什么的.

关于kwargs和docstrings的其他意见和建议也欢迎.

我目前正在使用 Sphinx 记录我的 Python 项目。在文档字符串的多行部分中包含项目符号列表时，我遇到了一个问题。

我想包括一个项目符号列表，但其中一项很长。我想要：

• 通过 Sphinx 正确呈现项目符号列表
• 但也有我的代码尊重 PEP8 关于行长度（<79）

你有什么建议让我为这个文档字符串做些什么：

class geography():
""" Class defining a geography (cities and distance matrix)

This class implements a geography with a list of named cities with their
associated coordinates in a plane. Helper functions enable to :

- give a visual representation of that geography
- give a visual representation of the distance matrix
- give a visual representation of a configuration, a configuration being the repartition of some or …

因此，我找到了与其他样式相关的帖子，并且我知道有关文档的 NumPy 页面，但我很困惑。我不明白如何将每个 kwargs 添加到方法的参数部分。这是来自给定的网页：

def foo(var1, var2, *args, long_var_name='hi', **kwargs):
    r"""Summarize the function in one line.

    Several sentences providing an extended description. Refer to
    variables using back-ticks, e.g. `var`.

    Parameters
    ----------
    var1 : array_like
        Array_like means all those objects -- lists, nested lists, etc. --
        that can be converted to an array.  We can also refer to
        variables like `var1`.
    var2 : int
        The type above can either refer to an actual Python type
        (e.g. ``int``), or …

也许是一个愚蠢的问题:如何__init__在编写C扩展时为特殊函数指定docstring ？对于普通方法,方法表提供了文档字符串.当我尝试帮助时,会显示以下自动生成的文档(myclass):

  __init__(...)
      x.__init__(...) initializes x; see help(type(x)) for signature

但这是我想要覆盖的.

我有一个参数设置为默认值的函数。我正在使用Numpy 样式的文档字符串，但我已经看到其他地方写的默认值。在文档字符串中写入“默认”的普遍接受的位置是什么？

def some_func(a_num=None, a_string=None):
    ''' A function that does something special.

    Parameters
    ==========
    a_num : int, default 100                        # is it written here?
        An important number.
    a_string : str, default 'foo'
        A useful string.  Default is 'foo'.         # or here?    

    '''

我想描述我的 Python 函数所期望的 DataFrame 结构，以及如下的口头描述：

def myfun(input):
    """ Does a thing.
    Parameters
    ----------
    input : pandas.DataFrame
        column 1 is called 'thing1' and it is of dtype 'i4'"
    """
    ...

感觉容易出错。有没有一种传统的方式来描述它？我在 Pandas 文档字符串文档中没有看到任何内容。

我总是在函数定义中使用类型提示，例如：

def foo(a: int, b: str) -> bool:
    pass

当我使用 PyCharm 自动文档字符串生成器在我的代码中生成文档字符串时，我得到了这个：

def foo(a: int, b: str) -> bool:
    """
    :param a: 
    :type a: 
    :param b: 
    :type b: 
    """
    pass

如您所见，我在函数本身中定义的类型值没有被 PyCharm 识别，我应该再次将它们写在 docstring 中。我如何让 PyC​​harm 为我自动生成这样的东西（从第一行读取类型值并将它们插入到文档字符串中）：

def foo(a: int, b: str) -> bool:
    """
    :param a:
    :type a: int
    :param b:
    :type b: str
    :rtype: bool
    """
    pass