Estoy usando Sphinx para documentar mi proyecto python. Tengo la extensión autodoc habilitada y tengo lo siguiente en mis documentos.¿Cómo puedo usar la extensión Autodoc de Sphinx para métodos privados?
.. autoclass:: ClassName
:members:
El problema es que solo documenta el non-private methods en la clase. ¿Cómo incluyo los métodos privados también?
¿Ha intentado utilizar un custom method para determinar si un miembro debe incluirse en la documentación, usando autodoc-skip-member?
Aquí hay una pista: imagina que lo privado significa "secreto".
Es por eso que Sphinx no los documentará.
Si no quiere decir "secreto", considere cambiar sus nombres. Evite usar el nombre de guion bajo único en general; no ayuda a menos que tenga una razón para mantener la implementación en secreto.
Esto parece al revés a lo que dice PEP-8 sobre lo privado. "En caso de duda, elija no públicos" http://www.python.org/dev/peps/pep-0008/ – svrist
@svrist: No al revés: ese es el punto exacto. Sphinx no documentará no públicamente. Si elige no público, no obtendrá la documentación automática. Si desea documentación, por otro lado, no elija no pública. Aquí, "duda" significa que tienes una buena razón para ambos y no puedes decidir. Si no tiene una * buena * razón para no público, tampoco tiene "duda". Hazlo público a menos que tengas una * buena * razón para no público. –
Pero, ¿qué sucede si está utilizando Sphinx para la documentación * internal *? –
No, privado significa privado para la clase y no debe usarse desde la API pública. No está destinado a significar secreto y para aquellos de nosotros que deseen utilizar Sphinx para la documentación completa de las clases, excluir los métodos privados es bastante molesto.
La respuesta anterior es correcta. Tendrá que usar un método personalizado ya que Sphinx no es compatible actualmente con autodoc junto con métodos privados.
Una forma de evitar esto es forzar explícitamente a Sphinx a documentar miembros privados. Esto se puede hacer añadiendo automethod hasta el final de los documentos nivel de clase:
class SmokeMonster(object):
"""
A large smoke monster that protects the island.
"""
def __init__(self,speed):
"""
:param speed: Velocity in MPH of the smoke monster
:type speed: int
.. document private functions
.. automethod:: _evaporate
"""
self.speed = speed
def _evaporate(self):
"""
Removes the smoke monster from reality. Not to be called by client.
"""
pass
Exactamente! Muchas gracias por esto: o) –
Sólo tenga en cuenta que '.. document private functions' y' .. automethod :: _FUNC_NAME' deben colocarse donde desee que se ubique la salida. No tienen que estar en la función '__init __()' de la clase relacionada . – dtlussier
¡gracias! También funcionó en el nivel de módulo para la función de módulo privado: IE '.. autofunction :: _my_private_module_function' en el módulo docstring y en mi archivo' .rst'. Desafortunadamente ': private-members:' no funcionó para funciones privadas de nivel de módulo. Creo que solo funciona en las clases. –
si está utilizando Sphinx 1.1 o superior, desde el sitio de la documentación esfinge en http://sphinx.pocoo.org/ext/autodoc.html,
:special-members:
:private-members:
Tenga en cuenta que puede hacer que esto sea un valor predeterminado para todas las clases utilizando el ['autodoc_default_flags'] (http://sphinx.pocoo.org/ext/autodoc.html# confval-autodo c_default_flags) configuración. –
En cuanto a apidoc code , podemos cambiar lo esfinge apidoc generar establecer una variable de entorno:
export SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance'
también puede agregar esta configuración en su Makefile (i f el programa utiliza una):
docs:
rm -rf docs/api
SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance' sphinx-apidoc -o docs/api/ intellprice
$(MAKE) -C docs clean
$(MAKE) -C docs html
puede agregar a este archivo a conf.py:
autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance']
Sphinx recientemente ha añadido una función para esto: https://bitbucket.org/birkenfeld/sphinx/issue/176/provide-option-to-include-private-and –
@KevinHorn Sería bueno si * sphinx-apidoc * lo tuviera también – mlt