python - sphinxs - sphinx documentation generator

¿Desea reStructuredText del autodoc de la esfinge?

Question

CPython no usa autodoc para su documentación, usamos prosa escrita a mano.

Para PEP 3144 (el módulo ipaddress), me gustaría usar sphinx-apidoc para generar la documentación de referencia inicial. Eso significa que quiero ejecutar una operación de dos pases:

1. Utilice sphinx-apidoc para emitir un proyecto Sphinx para el módulo que depende de autodoc

2. Ejecute un generador de sphinx que cree nuevos archivos de origen reStructuredText, con todas las directivas de autodoc reemplazadas por el contenido en línea reStructuredText y el marcado que produce el mismo resultado

El primer paso es sencillo, pero no tengo idea de cómo hacer el segundo paso y ni siquiera puedo pensar en buenas maneras de buscar proyectos existentes en este sentido.

Answer 1

No es una respuesta completa, más o menos un punto de partida:

autodoc traduce directivas automáticas a directivas python. Por lo tanto, se pueden usar eventos de autodoc para obtener las directivas de python traducidas.

Por ejemplo, si tiene el siguiente 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 creará

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

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

La siguiente extensión (o adición 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)

Te regalaré:

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

Sin embargo, como autodoc no emite ningún evento, cuando se completa la traducción, el procesamiento adicional realizado por autodoc debe adaptarse a las cadenas de documentación aquí.

Answer 2

Tuve el mismo problema y, por una vez, generé docs. He usado una solución bastante fea para parchear Sphinx, consulte Hacer que Sphinx genere documentación de clase RST desde pydoc .