Emitować reStructuredText from sphinx autodoc?

Question

CPython nie używa autodoc do dokumentacji - korzystamy z ręcznie pisanej prozy.

Dla PEP 3144 (moduł ipaddress), chciałbym użyć sphinx-apidoc do wygenerowania początkowej dokumentacji referencyjnej. Oznacza to, że chcę, aby uruchomić operację dwa-pass:

1. Zastosowanie sfinks-apidoc emitować projekt Sphinx dla modułu, który zależy od AutoDoc

2. Run budowniczym sfinks, który tworzy pliki źródłowe nowy reStructuredText , ze wszystkimi dyrektywami AutoDoc zastąpione zawartością inline reStructuredText i znaczników, które wytworzy

pierwszym krokiem jest proste, ale nie mam pojęcia jak to zrobić drugi krok, a nawet nie można myśleć o dobrym sposoby wyszukiwania f lub jakiekolwiek istniejące projekty zgodnie z tymi wytycznymi.

Answer 1

Miałem ten sam problem i po raz pierwszy generowanie dokumentów Użyłem dość brzydkiego rozwiązania do łatania Sphinx, zobacz Make Sphinx generate RST class documentation from pydoc.

Answer 2

Nie pełna odpowiedź, mniej lub bardziej punkt wyjścia:

autodoc przekłada dyrektyw auto do dyrektyw Pythonie. Tak więc można użyć zdarzeń autodoc, aby uzyskać przetłumaczone dyrektywy python.

Na przykład, jeśli istnieją następujące 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 stworzy

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

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

następujących rozszerzeniach (lub dodatek do 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) 

dadzą Ci :

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 

Jednak jako autodoc nie emituje żadnego zdarzenia, kiedy tłumaczenie jest zakończone, więc dalsze przetwarzanie wykonane przez autodoc musi zostać dostosowane do poleceń tutaj.