reStructuredText

Última edición el día 2020-12-14 a las 20:53.

Esta es la documentación que he recopilado para trabajar con Sphinx, un framework que tiene como proposito la creación de sitios web orientados a la documentación como es este mismo sitio.

Estilo de fuente

Para añadir estilo al texto hay que rodearlo con el siguiente formato:

  • Texto en negrita: **negrita**

Ejemplo: negrita

  • Texto remarcado en bloque de código: ``print()``

Ejemplo: print()

Listados

Hay dos tipos de listado que podemos definir:

  • Listado por puntos:

* Elemento 1
    * subelemento
* Elemento 2

Ejemplo:

  • Elemento 1
    • subelemento

  • Elemento 2

  • Listado numerico:

#. Un elemento
    #. Subelemento
#. Otro elemento

Ejemplo:

  1. Un elemento
    1. Subelemento

  • Listado vacio:

| Un elemento
| otro elemento

Ejemplo:

Un elemento
otro elemento
  • Listado horizontal:

.. hlist::
    :columns: 3

    * A list of
    * short items
    * that should be
    * displayed
    * horizontally

Ejemplo:

  • A list of

  • short items

  • that should be

  • displayed

  • horizontally

Bloque Literal

Un bloque literal es un bloque que se encuentra más desplazado a la derecha y se presenta con un título destacado:

Esto es un texto normal. Lo siguiente es un bloque literal::
    Esto es un texto literal,
    va un poco más desplazado a la derecha

Y listo

Ejemplo:

Esto es un texto normal. Lo siguiente es un bloque literal::

Esto es un texto literal, va un poco más desplazado a la derecha

Y listo

Línea de código

Es un bloque que tiene un prompt de estilo consola de python:

>>> Y aqui tenemos un codigo con prompt

Ejemplo:

>>> cd documents

Tablas

Hay dos formas comunes de crear una tabla:

  • Completa:

+--------------------+---------------+----------------+
| Cabecera 1         | Cabecera 2    | Cabecera 3     |
| Columna opcional   |               |                |
+====================+===============+================+
| Cuerpo 1, columna1 | columna 2     | columna 3      |
+--------------------+---------------+----------------+
| Cuerpo 2           | ...           |                |
+--------------------+---------------+----------------+

Ejemplo:

Cabecera 1 Columna opcional

Cabecera 2

Cabecera 3

Cuerpo 1, columna1

columna 2

columna 3

Cuerpo 2

  • Sencilla:

===== =====
A      B
===== =====
Falso xdd
Verda vss
Falso fas
===== =====

Ejemplo:

A

B

Falso

xdd

Verda

vss

Falso

fas

Encabezados

  • Encabezado sección:

=======================
Encabezado para sección
=======================
Encabezado para partes
######################
Encabezado para capitulos
*************************
Encabezado para subsecciones
----------------------------
para parrafos
"""""""""""""

Cada uno va generando distintos niveles de profundidad en la navegación de la web.

Campos destacados

son textos que podemos desctacar con : : y luego añadirles una descripción

:campo: Texto del campo

Ejemplo:

campo

Texto del campo

Mensajes

Podemos mostrar distintos mensajes de alerta entre otras cosas para los lectores:

  • Atención:

.. attention::
    Texto de atención

Ejemplo:

Atención

Texto de atención

  • Precaución:

.. caution::
    Texto de cuidado

Ejemplo:

Prudencia

Texto de cuidado

  • Peligro:

.. danger::
    Texto de peligro

Ejemplo:

Peligro

Texto de peligro

  • Error:

.. error::
    Texto de error

Ejemplo:

Error

Texto de error

  • Sugerencia:

.. hint::
    Texto de sugerencia

Ejemplo:

Consejo

Texto de sugerencia

  • Importante:

.. important::
    Texto de importante

Ejemplo:

Importante

Texto de importante

  • Nota:

.. note::
    Texto de nota

Ejemplo:

Nota

Texto de nota

  • Truco:

.. tip::
    Texto de consejo

Ejemplo:

Truco

Texto de consejo

  • Peligro:

.. warning::
    Texto de alerta

Ejemplo:

Advertencia

Texto de alerta

Imágenes

Podemos cargar imágenes y ajustarlas a nuestro gusto:

.. image:: picture.jpg
    :height: 100px
    :width: 200 px
    :scale: 50 %
    :alt: alternate text
    :align: right

Ejemplo:

alternate text

Entrada

Similar a la entrada de un blog o una red social

.. topic:: Topic Title

    Subsequent indented lines comprise
    the body of the topic, and are
    interpreted as body elements.

Ejemplo:

Topic Title

Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.

Barra Lateral

Una barra lateral a la derecha donde poner texto entre otras cosas

.. sidebar:: Sidebar Title
    :subtitle: Optional Sidebar Subtitle

    Subsequent indented lines comprise
    the body of the sidebar, and are
    interpreted as body elements.

Ejemplo:

Bloque de texto

Un bloque de texto es un texto que esta más desplazado a la derecha:

.. line-block::

    Lend us a couple of bob till Thursday.
    I'm absolutely skint.
    But I'm expecting a postal order and I can pay you back
        as soon as it comes.
    Love, Ewan.

Ejemplo:

Lend us a couple of bob till Thursday.
I’m absolutely skint.
But I’m expecting a postal order and I can pay you back
as soon as it comes.
Love, Ewan.

Bloque de código

En un bloque de código podemos escribir el código de nuestros programas y podemos hacerlo de distintas formas:

  • De forma sencilla:

.. code-block:: python

    def my_function():
        "just a test"
        print 8/2

Ejemplo:

def my_function():
    "just a test"
    print 8/2
  • Para un lenguaje de programación conocido:

.. code:: python

    def my_function():
        "just a test"
        print 8/2

Ejemplo:

def my_function():
    "just a test"
    print 8/2
  • Combinado con un texto explicativo:

.. compound::

    The 'rm' command is very dangerous.  If you are logged
    in as root and enter ::

        cd /
        rm -rf *

    you will erase the entire contents of your file system.

Ejemplo:

The “rm” command is very dangerous. If you are logged in as root and enter

cd /
rm -rf *

you will erase the entire contents of your file system.

  • Bloque de código numerado:

.. code-block:: javascript
    :linenos:

    function saludar(){
            console.log('Hola mundo');
        }

Ejemplo:

1
2
3
function saludar(){
        console.log('Hola mundo');
    }

Comenzar a partir de cierto número definido y poner nombre al archivo:

.. code-block:: python
    :caption: this.py
    :name: this-py

    print 'Explicit is better than implicit.'

Ejemplo:

this.py
print 'Explicit is better than implicit.'

O subrayar partes del código:

.. code-block:: python
    :emphasize-lines: 3,5

    def some_function():
        interesting = False
        print 'This line is highlighted.'
        print 'This one is not...'
        print '...but this one is.'

Ejemplo:

def some_function():
    interesting = False
    print 'This line is highlighted.'
    print 'This one is not...'
    print '...but this one is.'

Epígrafe

Introducir epígrafes en la página

.. epigraph::

    No matter where you go, there you are.

    -- Buckaroo Banzai

Ejemplo:

No matter where you go, there you are.

—Buckaroo Banzai

Índice

Crea un índice en base a todas las cabeceras de la página en la que se encuentra y la va organizando de forma jerárquica

  • Índice normal:

    .. contents:: Tabla de contenidos
    
  • Índice abreviado:

    .. contents:: Tabla reducida
        :depth: 2
    

Puedes ver un ejemplo de índice con el mismo índice de esta página.

Meta data

Genera etiquetas de meta data para la cabecera del documento html final:

.. meta::
    :description: The reStructuredText plaintext markup language
    :keywords: plaintext, markup language

.. meta::
    :description lang=en: An amusing story
    :description lang=fr: Une histoire amusante

Fecha y hora

Crea un registro de la fecha y hora a la que se ha guardado el documento:

.. |date| date::
.. |time| date:: %H:%M

Today's date is |date|.

This document was generated on |date| at |time|.

Ejemplo:

Today’s date is 2020-12-14.

This document was generated on 2020-12-14 at 20:53.

Clase destacada

Crea una clase especial que será reflejada en el índice:

.. class:: special

This is a "special" paragraph.

Ejemplo:

class Pensamiento

Aquello que da vueltas por la cabeza.

También existe la clase excepcional que no va indexada:

.. class:: exceptional remarkable

    An Exceptional Section
    ======================

    This is an ordinary paragraph.

Ejemplo:

exceptional remarkable

Y esto es un texto ordinario.

Crea una referencia a una clase y la indexa automáticamente:

.. class:: multiple

    First paragraph.

    Second paragraph.

Ejemplo:

class multiple

primer texto.

segundo texto.

Versiones

Define las versiones de la documentación expuesta:

.. versionadded:: 2.5

.. versionchanged:: 3.4

.. deprecated:: 3.2

Ejemplo:

Nuevo en la versión 2.5.

Distinto en la versión 3.4.

Obsoleto desde la versión 3.2.

Título

Crea un simple y sencillo título pequeño:

..code-block:: python

title

Ejemplo:

title

También existe la versión algo más centrada y detallada:

.. centered:: LICENSE AGREEMENT

Ejemplo:

LICENSE AGREEMENT

Crear un glosario

Crea tu propio glosario de palabras que se añadirán al index cuando se compile la web:

.. glossary::

    environment
        A structure where information about all documents under the root is
        saved, and used for cross-referencing.  The environment is pickled
        after the parsing stage, so that successive runs only need to read
        and parse new and changed documents.

    source directory
        The directory which, including its subdirectories, contains all
        source files for one Sphinx project.

Ejemplo:

environment

A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.

source directory

The directory which, including its subdirectories, contains all source files for one Sphinx project.

Cada título del glosario se enlaza directamente con el índice.