python - pyplot - Especificar objetivos para enlaces intersphinx a numpy, scipy y matplotlib

plot() python

Question

Siguiendo la documentación para configurar los enlaces de documentación de Sphinx entre paquetes, agregué

intersphinx_mapping = {''python'': (''http://docs.python.org/2'', None),
                       ''numpy'': (''http://docs.scipy.org/doc/numpy/'', None),
                       ''scipy'': (''http://docs.scipy.org/doc/scipy/reference/'', None),
                       ''matplotlib'': (''http://matplotlib.sourceforge.net/'', None)}

a mi conf.py , pero parece que no puede obtener enlaces a ningún otro proyecto que no sea el propio Python para funcionar. Por ejemplo

:term:`svg graphics <matplotlib:svg>`

simplemente me lleva a la página de índice, sin agregar el anclaje #term-svg esperado, y ni siquiera puedo ubicar el glosario para scipy o averiguar cómo determinar qué :ref: s o :term: son compatibles con un paquete .

¿Dónde puedo encontrar instrucciones sobre cómo especificar objetivos para :ref: s y :term: s en numpy , scipy y matplotlib ?

Para el caso, ¿cómo me enlace con Sphinx? Añadiendo

intersphinx_mapping[''sphinx''] = (''http://sphinx-doc.org/'', None)

y

:ref:`Intersphinx <intersphinx>`

no funciona

Answer 1

¿Dónde puedo encontrar instrucciones sobre cómo especificar objetivos para :ref: s y :term: s en numpy , scipy y matplotlib ?

Tengo un Gist con un puñado de mapeos intersphinx , que ahora incluye todos los numpy , scipy y matplotlib . Debería poder usar estas entradas directamente en intersphinx_mapping , dentro de su conf.py Si alguien tiene sugerencias para que se agreguen más entradas a esta lista, siéntase libre de publicar las solicitudes en los comentarios de la Gist.

Para todos estos paquetes, por la respuesta de fgoudra, recomiendo usar sphobjinv para decodificar e inspeccionar la sintaxis del archivo objects.inv para cada biblioteca. ( sphobjinv completa: soy el autor de sphobjinv .) Cada línea de los objects.inv (decodificados) objects.inv le brinda toda la información que necesita para construir una referencia intersphinx funcione; ver la documentación sphobjinv here .

numpy es complicado. A veces necesita un nombre completo, por ejemplo:

:func:`numpy.cross`

Otras veces (para funciones C, por ejemplo) puede simplemente hacer referencia al nombre base de la función PERO debe indicar explícitamente el dominio, por ejemplo:

:c:func:`PyArray_InnerProduct`

Sin embargo, otras veces puede que tenga que hacer referencia al dominio np personalizado, por ejemplo:

:np:func:`numpy.ma.append`

Realmente no hay forma de saber cuál es la sintaxis correcta sin consultar los objects.inv .

scipy es más o menos tan inescrutable como numpy . Las cosas se complican aún más con la introducción de numerosos dominios personalizados para los diversos scipy descuidados, por ejemplo:

:scipy-optimize:func:`scipy.integrate.newton_cotes`

Para matplotlib , parece que siempre debe proporcionar el nombre de objeto (completamente detallado) completamente especificado en la referencia, por ejemplo:

:meth:`matplotlib.axes.Axes.plot`

Sin embargo, todos los objetos del código matplotlib parecen residir en el dominio py predeterminado, lo que simplifica un poco las cosas.

Para cualquiera de estos, si tiene problemas para obtener un enlace para construir correctamente, lo primero que recurro es usar el rol genérico :obj: ej:

:obj:`matplotlib.axes.Axes.plot`

Esto construirá un enlace entre intersphinx independientemente del rol en el que se definió un objeto en particular, aunque creo que todavía tiene que especificar correctamente cualquier dominio relevante no predeterminado. Si la referencia no funciona correctamente con un :obj: role, entonces hay un error en el nombre del objeto o el dominio en alguna parte. Compruebe si hay errores tipográficos en ambos lugares.

Answer 2

Es posible especificar manualmente qué inventario buscar. Por ejemplo, si intersphinx_mapping[''sphinx''] = (''http://sphinx-doc.org/'', None) no funciona, siempre puede descargar el inventario y anexarlo manualmente a la asignación (por ejemplo, descargar desde http://sphinx-doc.org/objects.inv , guarde el archivo binario en sus documentos y anexe la ruta a él en la asignación, esto dará algo como:

intersphinx_mapping[''sphinx''] = (''http://sphinx-doc.org/'', (''objects.inv'', ), )

Para verificar si existe una referencia dentro del inventario, puede explorar el binario con el paquete sphobjinv python y verificar dónde está la referencia que desea.

Esto puede no ser una solución a su problema pero puede ayudar a depurar algunas cosas.