En Sphinx, puedo registrar un montón de palabras clave que siempre deben ser traducidos en los enlaces?

Question

Mis cadenas de documentación tienen referencias a otras clases de Python que he definido. Cada vez Sphinx se encuentra con una de estas clases, lo quiero para insertar un enlace a la documentación para esa otra clase. ¿Es esto posible en Sphinx?

En concreto, tengo una cadena de documentación como:

'''This class contains a bunch of Foo objects'''

Podría escribir:

'''This class contains a bunch of :class:`~foo.Foo` objects'''

pero yo preferiría que Sphinx encuentra todo Foo texto a juego y hace que parezca como si hubiera tecleado     : Clase: ~foo.Foo

Answer 1

Puede utilizar macros.

En mi proyecto, tengo un archivo de cabecera que contiene todas las clases "importantes" y funciones globales y su abreviatura. Dos líneas de ejemplo:

.. |PostItem| replace:: :class:`PostItem <hklib.PostItem>`
.. |PostNotFoundError| replace:: :class:`PostNotFoundError <hklib.PostNotFoundError>`

En mis archivos rst, que incluyen el archivo de cabecera. Entonces puedo utilizar las macros en cualquier archivo rst:

.. include:: defs.hrst

|PostItem| is a nice class. |PostNotFoundError|, on the other hand is not.

(Puede incluir cadenas de documentación de archivos de código fuente de Python, así, utilizando la extensión autogen. Las macros en los que serán reemplazados también.)

Acerca de su ejemplo: Yo añadiría Foo al archivo de encabezado y escribir la cadena de documentación de esta manera:

'''This class contains a bunch of |Foo| objects'''

Answer 2

Esfinge tiene un gran número de funciones de texto interpretados por esto.

http://sphinx.pocoo.org/markup /inline.html#cross-referencing-python-objects

  

Quiero entrar Foo y tienen Sphinx interpretarlo como si hubiera escrito: Clase: ~foo.Foo

Eso suena poco práctico. Parece que paralizaría RST tratando de análisis su texto. Buscando texto interpretado y las pocas reglas que citan RST soportes (*_|`) está sobre el límite que sea práctico.

Lo que están pidiendo podría conducir a RST tomar todo el día para comprobar cada Foo ejemplo, en todos los contextos y la razón es posible determinar si querías un enlace o no. Lo que quiere esto sólo en los casos de otro tipo, sin decoración de Foo; Búsqueda trivial y reemplazar no funcionaría.

Se puede meterse con docstring pre-procesamiento.

http://sphinx.pocoo.org/ext/autodoc.html # docstring-procesamiento previo

Esto puede permitir que intente una búsqueda global y reemplazar la estrategia en el texto de su cadena de documentación.