從 sphinx autodoc 發出 reStructuredText？

Question

CPython 的文檔不使用 autodoc - 我們使用手寫散文。

對於 PEP 3144（ipaddress 模塊），我想使用 sphinx-apidoc 生成初始參考文檔。 這意味着我要運行兩遍操作：

1. 使用 sphinx-apidoc 為依賴於 autodoc 的模塊發出 Sphinx 項目

2. 運行創建新 reStructuredText 源文件的 sphinx 生成器，所有 autodoc 指令都替換為內聯 reStructuredText 內容和產生相同輸出的標記

第一步很簡單，但我不知道如何做第二步，甚至想不出沿着這些路線搜索任何現有項目的好方法。

Answer 1

我有同樣的問題，有一次生成文檔我使用了非常丑陋的解決方案來修補 Sphinx，請參閱Make Sphinx generate RST class documentation from pydoc 。

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 

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 完成的進一步處理必須適應此處的文檔字符串。