从Sphinx autodoc中发出reStructuredText？

Question

CPython不使用自动文档生成工具来生成文档，我们使用手写的文学作品。

对于PEP 3144（ipaddress模块），我想使用sphinx-apidoc来生成最初的参考文档。这意味着我希望运行一个两个阶段的操作：

1. 使用sphinx-apidoc为依赖于autodoc的模块生成Sphinx项目

2. 运行一个Sphinx构建器，创建新的reStructuredText源文件，并用所有的autodoc指令替换为内联的reStructuredText内容和标记，以产生相同的输出

第一步很简单，但我不知道如何执行第二步，甚至无法想到任何现有项目沿着这些线路的好方法来搜索。

- ncoghlan

---

仅使用autodirective生成的rst文件（而不是完整的py-domain定义）并对其进行扩展有何问题？ - bmu

ipaddress已经有了详细的文档字符串，因此我不想为其余的文档复制粘贴并手动重新格式化它们。 - ncoghlan

那么为什么你要复制它们呢？你可以在自动指令之间编写额外的文档，并让Sphinx进行翻译，无需复制。抱歉，也许我没有理解你（或你的问题）。 - bmu

@ncoghlan：对提供的两个答案有任何反馈吗？我明天会颁发奖金。 - Steven Rumbalski

@bmu CPython文档构建过程没有启用autodoc（出于故意选择）。 - ncoghlan

@ncoghlan，由于我不知道不使用sphinx.autodoc的优点，所以我在https://dev59.com/AWPVa4cB1Zd3GeqP7qii上提出了这个问题。 - bmu

Answer 1

我曾经遇到类似的问题，在需要生成文档时，我使用了一种不太优雅的方法来修补Sphinx，可以参考这个链接：Make Sphinx generate RST class documentation from pydoc。

- Michal Čihař

---

+1，因为我认为这是通过autodoc完全格式化rst源的唯一方法。应该在autodoc中有一个事件可以获取它。（也请参阅我的答案）。 - bmu

Answer 2

这并不是一个完整的答案，只是一个起点：

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 

会创建一份API文档。

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没有发出事件，所以当翻译完成时，需要将对docstrings的进一步处理适应于这里的情况。

- bmu