python-sphinx - example - sphinx apidoc

¿Cómo creo un rol/roles global en Sphinx?

Question

Este es un seguimiento de "ReST Strikethrough" ReST tachado, pero en un contexto de Esfinge en lugar de ReST. Mi pregunta es si hay un lugar central en la esfinge donde colocar una directiva de "rol" o si esta directiva realmente tiene que repetirse en cada primer archivo dentro de una documentación de esfinge.

Con más detalle:

Es fácil definir estilos CSS personalizados para texto en línea (ver ReST Tachado como ejemplo) usando una directiva de rol:

.. role:: custom
   :class: custom

This is an :custom:`inline text`.

lo que se traduce en una representación html de

.. This is an <span class="custom">inline text</span>.  ..

Además, se puede agregar fácilmente una hoja de estilo personalizada a la esfinge (ver http://www.tinkerer.me/doc/theming.html ) donde se agrega un selector de clase CSS para controlar cómo se representa el texto "personalizado" (color, tachado, tamaño de fuente...)

Lo que me molesta es que en mis experimentos tuve que repetir la directiva de rol en cada archivo ReST que usaba el rol personalizado. ¿Hay un lugar "central" donde pueda definir esto una vez para todo el sitio?

Answer 1

Desde el ejemplo en el que documenta su proyecto usando la esfinge , puede usar include para sustituir un archivo global.rst , que contiene todas sus directivas de rol, en sus otros archivos. Desde este sitio:

La sintaxis:

.. include:: myfile.rst

Se "inline" el archivo dado ( myfile.rst ). Una convención común que uso es crear un archivo global.rst global llamado global.rst e incluirlo en la parte superior de cada página. Muy útil para enlaces a imágenes comunes o enlaces a archivos comunes, etc.

Answer 2

Parece que rst_prolog que se encuentra en el archivo conf.py es el lugar central que estaba buscando. Rst_prolog es "Una cadena de reStructuredText que se incluirá al comienzo de cada archivo fuente que se lea". En mi caso, simplemente agregué lo siguiente a conf.py:

rst_prolog = """
.. role:: test2
"""

Tenga en cuenta también que para mi propósito, la directiva de roles sin un atributo de clase funciona bien.

Obviamente, como Chris ha señalado, un rst_prolog que logra muchas cosas podría lograrse mediante la inclusión de un archivo global.rst . [Sin embargo, puede haber problemas con su ruta relativa. Tal vez sea mejor usar rst_prolog = open (''global.rst'', ''r''). Read () --unested]