Sphinx autodoc da ADVERTENCIA: py: target de referencia de clase no encontrado: tipo advertencia

Question

Tengo un código que usa una metaclase en python. Pero cuando se ejecuta autodoc esfinge que está dando el error:

WARNING: py:class reference target not found: type

El error está ocurriendo en una línea de un auto genera archivo .rst:

.. automodule:: API.list.blockList 
    :members: # this is the line in error 
    :show-inheritance: 

Y blocklist extiende API.list. lista que tiene \__metaclass__ establecido en mi metaclase.

Por lo que puedo decir, sphinx no cree que exista la clase de tipo incorporado. He intentado importar el tipo incorporado para que Sphinx se dé cuenta de que está allí, pero eso no funcionó.

Si elimino la asignación de metaclase de API.list.list y elimino la metaclase del código, entonces sphinx funciona bien.

Answer 1

Esto es simplemente un error en los documentos Python mismos: las referencias a algunos de los complementos de Python (incluido type) no resuelven correctamente (consulte, por ejemplo, https://bugs.python.org/issue11975).

Para hacer que la advertencia desaparezca, puede agregar la opción nitpick_ignore a su configuración de Sphinx. Por ejemplo, en el proyecto Astropy tenemos:

nitpick_ignore = [('py:class', 'type')] 

De hecho, hay bastantes excepciones que acabamos de poner a todos en un archivo separado que las leemos de. Ver:

https://github.com/astropy/astropy/blob/35501fcba6811705fcd53669742db8346727672d/docs/conf.py#L195

y para el archivo de excepciones en sí:

https://github.com/astropy/astropy/blob/35501fcba6811705fcd53669742db8346727672d/docs/nitpick-exceptions

Muchas de las excepciones en el archivo de arriba son específicos de Astropy, pero otros abordar algunas referencias rotas en Python y en Numpy, y puede ser genéricamente útil.