Cómo insertar código en reStructuredText
En reStructuredText existen dos formas de especificar ejemplos de código fuente. Una es usar la directiva «code», que es útil para ejemplos cortos de código; la otra es usar la directiva «include», que es ideal para incrustar ejemplos más extensos.
Ejemplo de un documento de reStructuredText usando la directiva code.
La directiva code es buena para indicar ejemplos cortos de código. Para usarla, se indica el nombre de la directiva y, como argumento, el nombre del lenguaje de programación en que está escrito el código. Por ejemplo, para un fragmento de código escrito en Python:
.. code:: python
# El programa ¡Hola mundo! para Python 3
print("¡Hola mundo!")
Al exportar como HTML, el ejemplo se vería así:
# El programa ¡Hola mundo! para Python 3 print("¡Hola mundo!")
Los lenguajes que se reconocen son los mismos reconocidos por el resaltador de sintaxis Pygments.
La directiva include es más conveniente para indicar ejemplos de código más extensos porque permite incluir el código directamente desde archivos externos. Para usarla, se indica el nombre de la directiva; como argumento, la ruta relativa al archivo de codigo fuente (relativa a la ubicación del documento de reStructuredText); y como opción, el nombre del lenguaje de programación en el que está escrito el código.
Por ejemplo, para incrustar en el documento un programa completo que busca palíndromos en un diccionario:
.. include:: palindromos.py :code: python
Al exportar como HTML, el ejemplo se vería así:
# Dominio público 2015. Ningún derecho reservado. """Ejercicio: Palíndromos. Abra cualquiera de los diccionarios disponibles en el directorio ``/usr/share/dict`` en el sistema operativo GNU. Imprima en pantalla: 1. La cantidad de palabras que son palíndromos. 2. La lista de palabras que son palíndromos. Decida usted cómo quiere que aparezcan los resultados en la pantalla. """ # FUNCIONES def es_palindromo(palabra): """Devuelve True si la palabra es un palíndromo. Si no, False.""" return palabra == palabra[::-1] # PROGRAMA PRINCIPAL palabras = open("/usr/share/dict/spanish").read().split() palindromos = [] for palabra in palabras: if es_palindromo(palabra): palindromos.append(palabra) print("Número de palíndromos:", len(palindromos)) print(palindromos)
Con la directiva include, cada cambio que hagamos en el código fuente se refleja en el documento cada vez que los exportemos como HTML, PDF, etc.
Temas relacionados: