how - sphinx python example

¿Cómo puedo usar la extensión Autodoc de Sphinx para métodos privados?

Question

Estoy usando Sphinx para documentar mi proyecto de python. Tengo habilitada la extensión autodoc y tengo lo siguiente en mis documentos.

.. autoclass:: ClassName
   :members:

El problema es que solo documenta los métodos no privados en la clase. ¿Cómo incluyo los métodos privados también?

Answer 1

¿Ha intentado usar un método personalizado para determinar si un miembro debe incluirse en la documentación, usando autodoc-skip-member ?

Answer 2

Aquí hay una pista: imagina que 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 de un solo nombre en general; no ayuda a menos que tenga una razón para mantener la implementación en secreto.

Answer 3

Mirando el código apidoc , podemos cambiar lo que sphinx-apidoc genera configurando 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 (si su paquete usa uno):

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

Answer 4

No, privado significa privado para la clase y que no debe usarse desde la API pública. No pretende ser secreto y para aquellos de nosotros que deseamos usar la esfinge 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 admite actualmente autodoc junto con métodos privados.

Answer 5

Puedes agregar esto al archivo conf.py :

autodoc_default_flags = [''members'', ''undoc-members'', ''private-members'', ''special-members'', ''inherited-members'', ''show-inheritance'']

Answer 6

Una forma de evitar esto es obligar explícitamente a Sphinx a documentar miembros privados. Puede hacer esto agregando automethod al final de los documentos de 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

Answer 7

si está utilizando sphinx 1.1 o superior, del sitio de documentación de sphinx en http://www.sphinx-doc.org/en/master/ext/autodoc.html ,

:special-members:
:private-members: