Emit reStructuredText da spodx autodoc?

Question

CPython non utilizza l'autodoc per la sua documentazione - usiamo la prosa scritta a mano.

Per PEP 3144 (il modulo ipaddress), mi piacerebbe utilizzare sphinx-apidoc per generare la documentazione di riferimento iniziale. Ciò significa che voglio fare funzionare un funzionamento a due passaggi:

1. Usa sfinge-apidoc per emettere un progetto Sfinge per il modulo che dipende autodoc

2. Eseguire un costruttore sfinge che crea file di origine nuova reStructuredText , con tutte le direttive AutoDoc sostituiti con contenuto in riga reStructuredText e markup che produce lo stesso output

il primo passo è semplice, ma non ho idea di come fare il secondo passo e non possono nemmeno pensare di buona modi per cercare f o qualsiasi progetto esistente seguendo queste linee.

Answer 1

Ho avuto lo stesso problema e per una volta la generazione di documenti ho usato una soluzione abbastanza brutta per applicare la patch a Sphinx, vedere Make Sphinx generate RST class documentation from pydoc.

Answer 2

Non è una risposta completa, più o meno un punto di partenza:

autodoc traduce direttive auto alle direttive pitone. Quindi si possono usare gli eventi autodoc per ottenere le direttive Python tradotte.

Per esempio, se si hanno le seguenti 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 creerà

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

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

L'estensione seguente (o aggiunta a 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) 

vi darà :

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 

Tuttavia come autodoc emette nessun caso, quando la traduzione è completata, così un'ulteriore elaborazione svolto da autodoc deve essere adattato alle docstrings qui.