Estoy tratando de crear automáticamente api docs para una gran base de código de Python usando Sphinx.

He intentado usar build_modules.py y sphinx-apidoc. Con cualquiera de los dos, puedo hacer que los primeros documentos se creen correctamente en mi directorio de salida para los paquetes y los módulos de nivel superior.

Sin embargo, cuando construyo usando

make html

Da miles de errores de este tipo:

<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'

para cada clase y método en el código base. Con algo de experimentación, creo que he descubierto que las directivas de resumen automático / autoclase están creando toctrees que esperan que haya primeros archivos para cada clase y método.

Aparte de las advertencias, la documentación parece funcionar bien, pero me gustaría deshacerme de ellas y creo que puedo haber configurado mal algo.

También he intentadonipype / herramientas a mucho el mismo efecto.

Yo modifiquéapigen.py ybuild_modref_templates.py para crear los primeros apéndices para cada uno de estos documentos "faltantes", con autoclase / autofunction / automethods según corresponda. Sin embargo, la compilación lleva bastante tiempo (10 minutos) y finalmente se bloquea debido a errores de memoria en el último paso de compilación.

Aquí hay un ejemplo de módulo rst file que crea todas las advertencias:

src Package
===========

:mod:`src` Package
------------------

.. automodule:: src.__init__
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example1` Module
------------------------------------

.. automodule:: src.Example1
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example2` Module
------------------

.. automodule:: src.Example2
    :members:
    :undoc-members:
    :show-inheritance:

¡Gracias por cualquier consejo sobre cómo hacer que estas advertencias se resuelvan! Me gustaría mantenerme alejado de cualquier solución que implique la modificación de los archivos de paquete de sitio de la esfinge.