从 sphinx autodoc 发出 reStructuredText？答案

【问题标题】：Emit reStructuredText from sphinx autodoc?从 sphinx autodoc 发出 reStructuredText？
【发布时间】：2012-05-09 19:00:45
【问题描述】：

CPython 的文档不使用 autodoc - 我们使用手写散文。

对于 PEP 3144（ipaddress 模块），我想使用 sphinx-apidoc 来生成初始参考文档。这意味着我要运行两次操作：

使用 sphinx-apidoc 为依赖于 autodoc 的模块生成 Sphinx 项目
运行一个 sphinx 构建器来创建新的 reStructuredText 源文件，所有 autodoc 指令都替换为内联 reStructuredText 内容和生成相同输出的标记

第一步很简单，但我不知道如何进行第二步，甚至想不出好的方法来搜索任何现有的项目。

【问题讨论】：

使用 autodoc 生成的 rst 文件有什么问题（所以只有自动指令没有完整的 py 域定义）并扩展它们？
ipaddress 已经有大量的文档字符串，所以我不想为其余文档手动复制和粘贴它们并重新格式化它们。
那你为什么要复制它们呢？您可以在自动指令“之间”编写附加文档并让 sphinx 翻译它，无需复制。对不起，也许我不明白你（或你的问题）。
@ncoghlan：对所提供的两个答案有何反馈？明天我会奖励赏金。
@bmu CPython 文档构建过程没有启用自动文档（有意选择）

标签： python python-sphinx autodoc

【解决方案1】：

不是一个完整的答案，或多或少是一个起点：

autodoc 将自动指令转换为 python 指令。因此可以使用 autodoc 事件来获取翻译后的 python 指令。

例如，如果您有以下mymodule.py：

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
This is my module.
"""

def my_test_func(a, b=1):
    """This is my test function"""
    return a + b 

class MyClass(object):
    """This is my class"""

    def __init__(x, y='test'):
        """The init of my class"""
        self.x = float(x)
        self.y = y 

    def my_method(self, z): 
        """This is my method.

        :param z: a number
        :type z: float, int
        :returns: the sum of self.x and z
        :rtype: float
        """
        return self.x + z

sphinx-apidoc 将创建

mymodule Module
===============

.. automodule:: mymodule
    :members:
    :undoc-members:
    :show-inheritance:

以下扩展名（或对conf.py的补充）：

NAMES = []
DIRECTIVES = {}

def get_rst(app, what, name, obj, options, signature,
            return_annotation):
    doc_indent = '    '
    directive_indent = ''
    if what in ['method', 'attribute']:
        doc_indent += '    '
        directive_indent += '    '
    directive = '%s.. py:%s:: %s' % (directive_indent, what, name)
    if signature:  # modules, attributes, ... don't have a signature
        directive += signature
    NAMES.append(name)
    rst = directive + '\n\n' + doc_indent + obj.__doc__ + '\n'
    DIRECTIVES[name] = rst 

def write_new_docs(app, exception):
    txt = ['My module documentation']
    txt.append('-----------------------\n')
    for name in NAMES:
        txt.append(DIRECTIVES[name])
    print '\n'.join(txt)
    with open('../doc_new/generated.rst', 'w') as outfile:
        outfile.write('\n'.join(txt))

def setup(app):
    app.connect('autodoc-process-signature', get_rst)
    app.connect('build-finished', write_new_docs)

会给你：

My module documentation
-----------------------

.. py:module:: mymodule


This is my module.


.. py:class:: mymodule.MyClass(x, y='test')

    This is my class

    .. py:method:: mymodule.MyClass.my_method(z)

        This is my method.

        :param z: a number
        :type z: float, int
        :returns: the sum of self.x and z
        :rtype: float


.. py:function:: mymodule.my_test_func(a, b=1)

    This is my test function

但是，由于autodoc 不会发出任何事件，所以当翻译完成时，因此 autodoc 所做的进一步处理必须适应此处的文档字符串。

【讨论】：

【解决方案2】：

我遇到了同样的问题，有一次生成文档时我使用了非常丑陋的解决方案来修补 Sphinx，请参阅 Make Sphinx generate RST class documentation from pydoc。

【讨论】：

+1 因为我认为这是使 rst-source 完全由 autodoc 格式化的唯一方法。 autodoc 中应该有一个事件来获取它。（另见我的回答）。