使用 Sphinx 记录函数中的对象修改

Question

我有一个函数，例如：

def my_function(obj, X):
    """My function.

    :param obj: An instance of object.
    :type obj: object

    :param A: An array
    :type A: :class:`numpy.ndarray`

    """

    obj.fs['X'] = X.shape

    obj.d['v'] = obj.fs['X'][0]
    obj.d['t'] = obj.fs['X'][1]
    obj.d['m'] = obj.fs['X'][2]

    #: Comment here
    hv = obj.fs['Uh'] = (obj.d['h'], obj.d['v'])
    hh = obj.fs['Vh'] = (obj.d['h'], obj.d['h'])
    h1 = obj.fs['bh'] = (obj.d['h'], 1)

    # Etc...

    return None

我用 Sphinx 记录这个函数使用：

.. autofunction:: path.my_function

我想要一种记录代码块的方法。我知道有 #: Comment 但似乎不适用于 .. autofunction::.

Answer 1

我认为这是一种误解，因为 API 中记录的是构造的签名（例如 classes、方法、函数等），而不是代码的内部部分.如前所述这就是 PEP 257 定义为文档字符串的使用。

唯一的例外是记录属性（这是 #: 语法在 Sphinx 中的用途），但通常您只公开 class 级别和模块级别的用户定义属性（从不使用函数范围的属性）。

根据您的描述，正确的选择是使用 a code region 拆分构造中的内部区域。（但请注意，这种内部文档风格应该只涉及那些将超越 API 并查看源代码的开发人员。函数实现的任何功能都应该根据参数和 returns 因此隐藏了任何内部结构。）

def my_function(obj, X):
    """My function.

    :param obj: An instance of object.
    :type obj: object

    :param A: An array
    :type A: :class:`numpy.ndarray`

    """

    # region Adding attributes to argument object.
    obj.fs['X'] = X.shape

    obj.d['v'] = obj.fs['X'][0]
    obj.d['t'] = obj.fs['X'][1]
    obj.d['m'] = obj.fs['X'][2]
    # endregion
    
    # region USUALLY A ONE-LINER HERE
    # If the above isn't enough expand it by writing more comment lines.
    hv = obj.fs['Uh'] = (obj.d['h'], obj.d['v'])  # Inline comment.
    hh = obj.fs['Vh'] = (obj.d['h'], obj.d['h'])
    h1 = obj.fs['bh'] = (obj.d['h'], 1)
    # endregion

    # Etc...

    return None

但是，在极少数情况下，上述情况并非没有一些可能的例外情况。问题是 autodoc 扩展遵循上面解释的普遍规则，因此对于 .. autofunction:: 和 ..automethod:: 指令，文档明确指出：

.. autofunction::

These work exactly like autoclass etc., but do not offer the options used for automatic member documentation.

一个违背先前逻辑并且看起来与您的用例相似的示例是记录一个向创建的实例添加额外属性的工厂方法。您可以通过 cross-referencing the extra attributes. However this would still violate the Principle of least astonishment 和通常的封装逻辑在文档字符串或 .rst 文件中以文本方式说明这一点，因为用户期望 class/object 的属性是对象最初声明的属性。

但是，如果您真的想要这种 OO 设计，则有一个技术解决方案。而不是简单地使用：

.. autofunction:: path.my_function

使用Python域.. py:attribute::声明.rst文件中的变量。这样做的缺点是它不会提取您在源代码中使用 :# 语法编写的文本。但是，它确实允许完全按照您在原始问题中的预期实施文档。

.. autofunction:: path.my_function

   .. py:attribute:: path.my_function.hv 
      
      Some text about the attribute.

   .. py:attribute:: path.my_function.hh 
      
      Some text about the attribute.

   .. py:attribute:: path.my_function.h1 
      
      Some text about the attribute.

使用 Sphinx 记录函数中的对象修改

Document object modification in function using Sphinx

python

python-sphinx

autodoc