Sto usando una combinazione di docstring e Sphinx per documentare i miei programmi Python. Con l'autodoc di Sphinx, posso scrivere molta documentazione nel sorgente come docstring. C'è uno standard per la quantità di documentazione da inserire in ciascuno?
Ad esempio,
caso 1 è index.rst
.. automodule:: foo
:members:
e foo.py
"""documentation"""
class Foo:
"""documentation""""
def bar(self, baz):
"""more documentation"""
caso 2 index.rst
.. automodule:: foo
e 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
e foo.py
"""documentation
Classes:
Foo
"""
class Foo:
"""documentation
Methods:
bar
""""
def bar(self, baz):
"""more documentation"""
Il 1 è facile da mantenere, ma le docstring nella fonte mancano di informazioni. Il 2 inserisce tali informazioni nelle docstring di origine, ma è un po 'più difficile da mantenere ed è un po' più difficile da leggere. 3 è facile da leggere e ha una documentazione completa nel codice sorgente, ma è molto difficile da mantenere, e quando si utilizza la sfinge per generare la documentazione, alcune informazioni vengono ripetute. (Sembrerà qualcosa del tipo:
foo:
documentation
classes:
Foo
Foo:
documentation
methods:
baz
baz