Es sobre todo una cuestión de historia, pero también una cuestión de preferencia personal (y de proyecto). En estos días, puede obtener documentos muy utilizables basándose principalmente en documentos y luego, tal vez, agregando prosa adicional a su alrededor.
La documentación de CPython, sin embargo, es anterior a la existencia de Sphinx (de hecho, Georg Brandl escribió la versión inicial de Sphinx para reemplazar el antiguo sistema de documentación de CPython).
Así que, como una cuestión de política, los documentos y la documentación en prosa todavía se mantienen por separado sin depender del uso de autodoc.
También no permiten el uso de docstrings reStucturedText en la biblioteca estándar que reduce aún más los beneficios de usar autodoc. (Ver Q 10 en el PEP 287 Q & A: http://www.python.org/dev/peps/pep-0287/#questions-answers)
Por último, Georg Brandl pointed out que CPython está en una posición algo único que hay que tener cuidado para asegurarse de que la versión de la biblioteca estándar que está proporcionando el docstrings cuando Sphinx se ejecuta es exactamente el mismo para el que está generando la documentación. Sería demasiado fácil introducir accidentalmente la versión incorrecta, así como crear una fuerte dependencia entre tener una versión de Python en funcionamiento y poder volver a generar la documentación.
En el lado autodoc, tiene el problema de que al editar documentación basada en autodoc, no puede ver fácilmente los contenidos del docstring en línea, por lo que puede ser difícil asegurarse de que el texto docstring y la prosa adicional se leen bien juntos. Ese problema puede mitigarse a través de una solución de actualización automática del navegador como http://pymolurus.blogspot.com.au/2012/01/documentation-viewer-for-sphinx.html
autodoc también tiene un problema con las dependencias de las reconstrucciones, ya que no agrega automáticamente las dependencias correctas en los archivos fuente de Python. Definitivamente he tenido problemas donde las docstrings han cambiado, pero Sphinx no ha regenerado los archivos de salida relevantes. (No creo que esto haya sido resuelto, pero si se ha resuelto en versiones más recientes de Sphinx, avísenme en los comentarios y eliminaré esta observación).
Si bien creo que se obtiene una mejor documentación y mejores cadenas de documentación manteniendo por separado (debido a que los dos estilos de escritura no son exactamente los mismos y primas docstrings son generalmente más fáciles de leer un texto tan claro de lo que son cuando marcado con reStructuredText), es un enfoque que implica costos bastante elevados en el esfuerzo de mantenimiento adicional y un mayor riesgo de incoherencia.
En consecuencia, para la mayoría de los proyectos de Python de terceros, mi consejo sería en realidad para evitar siguiendo el ejemplo de la biblioteca estándar y en su lugar:
- docstrings uso reRestructuredText (ver PEP 287: http://www.python.org/dev/peps/pep-0287/)
- uso apidoc/autodoc
- añadir documentación adicional prosa alrededor de las cadenas de documentación incorporados automáticamente en lugar de como un sustituto
- utilizar un enfoque autoupdating tales como la vinculada arriba para ver qué tan bien las cadenas de documentación leen como parte de la documentación
Si bien no es una solución perfecta, este enfoque hace ahorrar un poco de la duplicación de esfuerzos en mantener las dos cadenas de documentación y la documentación de la prosa hasta fecha.
gracias por esta explicación. Personalmente, no creo que las cadenas en bruto sean más fáciles de leer como texto sin formato, especialmente cuando se utiliza 'numpydoc' https://raw.github.com/numpy/numpy/master/doc/EXAMPLE_DOCSTRING.rst.txt. Entonces continuaré usando autodoc. – bmu