División de documentación entre cadenas de documentación y esfinge

7

Estoy usando una combinación de cadenas de documentación y Sphinx para documentar mis programas de Python. Con el autodoc de Sphinx, puedo escribir una gran cantidad de documentación en la fuente como docstrings. ¿Hay algún estándar para la cantidad de documentación que hay que poner en cada uno?

Por ejemplo,

caso 1 es index.rst

.. automodule:: foo
   :members:

y foo.py

"""documentation"""

class Foo:
"""documentation""""

    def bar(self, baz):
        """more documentation"""

caso 2 index.rst

.. automodule:: foo

y foo.py

"""documentation

.. autoclass:: Foo

"""

class Foo:
"""documentation

.. automethod:: bar

""""

    def bar(self, baz):
        """more documentation"""

caso 3 index.rst

.. automodule:: foo
   .. autoclass:: Foo
      .. automethod:: bar

y foo.py

"""documentation

Classes:
    Foo

"""

class Foo:
"""documentation

Methods:
    bar

""""

    def bar(self, baz):
        """more documentation"""

El 1 es fácil de mantener, pero las cadenas de documentación en la fuente carecen de información. El 2 pone esa información en las cadenas de documentación de origen, pero es un poco más difícil de mantener y es un poco más difícil de leer. El 3 es fácil de leer y tiene documentación completa en el código fuente, pero es muy difícil de mantener, y cuando se usa la esfinge para generar la documentación, se repite algo de información. (Se verá algo así como:

foo:
    documentation
    classes:
        Foo

    Foo:
        documentation
        methods:
            baz
        baz
    
pregunta darkfeline 24.01.2013 - 03:51

1 respuesta

10

La biblioteca estándar de Python mantiene toda la documentación de Sphinx por separado, renunciando por completo a la función de autodoc y usa cadenas de documentos mucho más breves en los archivos de origen. Por lo tanto, la siguiente práctica es quizás la mejor:

  • Las cadenas de texto en el código fuente no deben usar las directivas de Sphinx, ya que solo se usa el formato ligero de reST para facilitar la lectura. Debido a que (bueno) el código de Python es bastante claro por sí mismo, mantenga las cadenas de documentación informativas pero simples. Estos deben ser principalmente para desarrolladores de proyectos y cualquier persona que busque en el código fuente.
  • La documentación de usuario final real (o desarrolladores para bibliotecas) debe ser atendida por Sphinx. Use Autodoc cuando sea apropiado, siguiendo lo anterior.
respondido por el darkfeline 28.01.2013 - 00:35

Lea otras preguntas en las etiquetas