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.

Índice

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:

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

Links ¶

Para crear un enlace podemos utilizar el siguiente código:

Enlaces, para ir a google `aquí <https://google.es>`_.

Ejemplo:

Enlaces, para ir a google aquí.

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:

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:

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.