相关疑难解决方法(0)

如何使用Python的文档字符串记录带参数的方法？

编辑: PEP 257给出了这个例子:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

这是大多数Python开发人员使用的约定吗？

Keyword arguments:
<parameter name> -- Definition (default value if any)

我期待一些更正式的东西,比如

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real …

我有带有对象属性的Python类,它们只被声明为运行构造函数的一部分,如下所示:

class Foo(object):
    def __init__(self, base):
        self.basepath = base

        temp = []
        for run in os.listdir(self.basepath):
            if self.foo(run):
                temp.append(run)
        self.availableruns = tuple(sorted(temp))

如果我现在使用help(Foo)或尝试Foo在Sphinx中记录,则不显示self.basepath和self.availableruns属性.这对我们API的用户来说是一个问题.

我已经尝试寻找一种标准方法来确保解析器可以找到这些"动态声明"的属性(最好是docstring'd),但到目前为止还没有运气.有什么建议？谢谢.

我正在阅读sphinx文档页面,具有讽刺意味的是,关于var,ivar和cvar之间差异的文档非常缺乏.我想知道是否有人可以解释内联代码中每个不同名称空间之间的区别.

例:

class foo(object):
    """
      :var str first:
      :ivar str last:
      :cvar str middle:
    """

这些狮身人面像标签中的每一个如何彼此不同,我如何知道哪一个是正确使用的设计？

我写了一个 python 类，并用 sphinx 制作了文档。例如，该类如下所示：

class Aclass(object):
    """ my class """

    def __init__(self):
        """ constructor """

        self.a = None
        """ doc for attribute a """

        self._prop = None

    def _get_prop(self):
        """ getter prop """
        return self._prop

    def _set_prop(self, val):
        """ setter prop """
        self._prop = val

    prop = property(_get_prop, _set_prop)
    """ a property """

    def square(self):
        """ return square of a """
        return self.a**2

现在，为了做文档，我在第一个文件中写道：

.. autoclass:: aclass.Aclass
   :members:

它的一切OK，并且a，prop和square出现在文档。

但是如果我尝试分别记录属性和方法，sphinx 会说它无法找到属性 a 但它适用于 …

所有其他类型(类,属性,方法等)工作正常,但当autosummary获取实例属性时,它会引发" WARNING: failed to import AClass.a"错误.奇怪的是,表格是使用以下autodoc代码文档的链接绘制的,但doc summary列为空.

有没有人有这个工作,或有任何想法可能是错的？

显示包含链接但没有文档的表格:

显示autodoc正在工作(如果没有它,上面的链接将无法实现):

我也尝试过其他形式的文档,例如#: ...样式等.所有相同的结果.同样,同一模块中的其他所有工作都可以.我在自动分析表中查看方法等的文档.

示例类:

class AClass(object):
    def __init__(self):
        self.a = 10
        """
        An example instance attribute

        :type: int
        """

示例ReST:

.. autosummary::

    AClass.a

我正在使用Sphinx 1.2.3