Python Sphinx haciendo referencia a nombres largos

Question

Estoy trabajando en la documentación de mi módulo Python (usando Sphinx y reST), y estoy descubriendo que al hacer referencias cruzadas con otros objetos de Python (módulos, clases, funciones, etc.) el objeto completo el nombre termina siendo increíblemente largo. A menudo es más de 80 caracteres, lo que me gustaría evitar a toda costa.

Aquí se muestra un ejemplo:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    :class:`module1.module2.module3.module4.module5.ReallyLongExampleClassName` 

    ''' 

La cuestión es que al crear la documentación de la claseReallyLongExampleClassName, he generado por el nombre de ruta completo module1.module2.module3.module4.module5.ReallyLongExampleClassaName .

Me pregunto si hay alguna manera de resolver esto? He intentado los siguientes métodos, sin éxito:

1) Agregar un salto de línea en el medio del nombre del módulo. Ejemplo:

:class:`module1.module2.module3.module4. 
module5.ReallyLongExampleClassName` 

2) Hacer referencia al nombre de clase de una manera diferente (pero aún Python importable). Ejemplo:

:class:`module1.module2.ReallyLongClassName` 

Creo que desde la documentación de ReallyLongClassName está ligada a los nombres de ruta completos que Sphinx no puede correlacionar la versión acortada con la versión totalmente identificado.

Cualquier ayuda será muy apreciada.

Edición 04/05/2012:

De acuerdo con la respuesta/sugerencia de j13r (ver más abajo) He intentado lo siguiente:

:class:`module1.module2.module3.module4.module5\ 
ReallyLongExampleClassName` 

Y esto funcionó con éxito. La única advertencia para hacer que esto funcione, es que la segunda línea no debe tener espacios antes (lo cual es bastante frustrante cuando se usa esto en una docstring). Por lo tanto para hacer mi ejemplo original de trabajar que se vería así:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    :class:`module1.module2.module3.module4.module5.\ 
ReallyLongExampleClassName` 

    ''' 

Niza, y feo. Si tuviera que poner espacios antes de "ReallyLongExampleClassName" para sangrarlo al mismo nivel que la línea superior, la salida incluiría los espacios y, por lo tanto, Sphinx trataría de hacer referencia a algo como "module1.module2.module3.module4.module5. ReallyLongExampleClassName. "

También debo señalar que he intentado otras dos variantes de este, que no funcionaba:

# Note: Trying to put a space before the '\' 
    :class:`module1.module2.module3.module4.module5. \ 
ReallyLongExampleClassName` 

    # Note: Trying to leave out the '\' 
    :class:`module1.module2.module3.module4.module5. 
ReallyLongExampleClassName` 

que estaba buscando una solución que no implicara la destrucción del formato de la cadena de documentación, pero supongo lo hará ... Creo que en realidad prefiero una línea que va más allá de 80 caracteres a esto.

Gracias a j13r por la respuesta!

Answer 1

De acuerdo con la documentación de la esfinge (http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects) se puede utilizar un punto antes de su clase de objetivo:

:class:`.ReallyLongExampleClassName` 

o

:class:`.module5.ReallyLongExampleClassName` 

y dejar que la búsqueda de la esfinge de la clase:

... si el nombre es precedido por un punto, y hay una coincidencia exacta se encuentra, el objetivo se toma como un sufijo y todos los nombres de objeto con el sufijo que se buscan . Por ejemplo,: py: meth: .TarFile.close hace referencia a la función tarfile.TarFile.close(), incluso si el módulo actual no es tarfile. Como esto puede ser ambiguo, si hay más de una coincidencia posible, recibirás una advertencia de Sphinx.

Answer 2

puñalada salvaje en la oscuridad.Tal vez esto funciona:

:class:`module1.module2.module3.module4.\ 
module5.ReallyLongExampleClassName` 

Sería Python válida

import scipy.\ 
stats 

Answer 3

Puede utilizar ~ como prefijo, que hace exactamente lo que quiere.

http://sphinx-doc.org/markup/inline.html#xref-syntax

Answer 4

Otra estrategia es utilizar reST Substitutions. Esto le permitirá ahorrar más espacio en el texto llamando a la :class: referencia cruzada más adelante:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    |ReallyLongExampleClassName| 

    .. |ReallyLongExampleClassName| replace:: 
            :class:`.ReallyLongExampleClassName` 

    ''' 

Si se refiere a la misma clase en muchas de sus archivos, en su lugar podría poner la sustitución en su Archivo Sphinx conf.py, usando la configuración rst_epilog. De la documentación Sphinx:

rst_epilog

Una cadena de reStructuredText que se incluye al final de cada archivo fuente que se lee. Este es el lugar correcto para agregar sustituciones que deberían estar disponibles en cada archivo. Un ejemplo:

rst_epilog = """ 
.. |psf| replace:: Python Software Foundation 
""" 

Nuevo en la versión 0.6.

Luego, su cadena de documentación que acaba de ser:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    |ReallyLongExampleClassName| 

    '''