Escribiendo en reStructuredText#

reStructuredText es el lenguaje de marcado de texto sin formato predeterminado utilizado por Sphinx. Esta sección es una breve introducción a los conceptos y la sintaxis de reStructuredText (reST) que comúnmente se utiliza para crear documentación.

Creación de archivo#

Antes de iniciar con la explicación de reStructuredText, siga estos pasos para crear su primer proyecto.

Cree la carpeta de su proyecto en la Carpeta content .

Prudencia

Asegúrese de que el nombre de su carpeta no contenga espacios, en caso de tener más de dos palabras use snake_case.

Cree su archivo .rst dentro de la carpeta de su proyecto.

Directory Tree

.
├── carpeta_ejemplo
│ ├── archivo1.rst
├── index.rst
├── Módulos
├── PDF
└── Reportes

Prudencia

De la misma manera, asegúrese de que el nombre de su archivo no contenga espacios.

Si dentro de la carpeta de su proyecto tiene más de un archivo, cree un archivo index.rst, y los archivos que necesite, por ejemplo:

Directory Tree

.
├── carpeta_ejemplo
│   ├── archivo1.rst
│   ├── archivo2.rst
│   ├── archivo3.rst
│   ├── index.rst
├── index.rst
├── Módulos
├── PDF
└── Reportes

Nota

El archivo index.rst se crea únicamente cuando se tiene más de un archivo .rst. Este archivo permite agrupar todos los archivos de su carpeta en uno solo y tratarlo como un enlace hacia el contenido principal. (Consulte Preparar toctree para más detalles).

Si necesita otras secciones dentro de su proyecto, cree una subcarpeta y dentro de ella los archivos que necesite.

Directory Tree

.
├── carpeta_ejemplo
│   ├── archivo1.rst
│   ├── archivo2.rst
│   ├── archivo3.rst
│   ├── index.rst
│   └── subcarpeta
│       ├── archivo1.rst
│       ├── archivo2.rst
│       ├── archivo3.rst
│       └── archivo4.rst
├── index.rst
├── Módulos
├── PDF
└── Reportes

Secciones#

Las secciones resultan útiles para organizar y estructurar su documentación, ya que permiten dividir el contenido en partes más pequeñas y establecer una jerarquía clara.

En lugar de imponer un número y un orden fijos para el título de la sección, el orden aplicado será el orden encontrado. El primer estilo hallado se considerará como un título principal (similar al HTML H1), el segundo estilo será un subtítulo, el tercero será otro subtítulo, y así sucesivamente.

A continuación, se muestran ejemplos de títulos y subelementos

====================
Título de la Sección
====================

Introducción
============

Sección 1
---------

Subsección 1.1
^^^^^^^^^^^^^^
Subsección 1.2
^^^^^^^^^^^^^^

Sección 2
---------

Importante

La longitud de la cadena de texto debe ser igual a la longitud del símbolo que se va a utilizar, por ejemplo:

Correcto#

Título con la longitud correcta
===============================

Incorrecto#

Título con la longitud incorrecta
===========

Párrafos#

El párrafo es el bloque más básico en un documento reST. Los párrafos son simplemente fragmentos de texto separados por uno o más espacios en blanco.

Importante

Como en Python, la sangría es significativa en reST, por lo que todas las líneas del mismo párrafo debe estar alineado a la izquierda con el mismo nivel de sangría.

Resaltos#

El marcado en línea estándar de reST es muy sencilla.

Utilice un asterisco para un énfasis (cursiva):

*text*

Utilice dos asteriscos para un fuerte énfasis (negrita):

**text**

Utilice comillas inversas para un ejemplo de tipo código en línea:

``text``

Prudencia

Al utilizar alguno de los resaltos anteriores, debe tener cuidado con los espacios. Si existe un espacio entre el caracter y la palabra, la instrucción no será reconocida.

Listas#

Listas ordenadas y no ordenadas#

Para crear una lista no ordenada, simplemente coloque un asterisco * al principio del texto y aplique la sangría adecuada.

Del mismo modo, las listas numeradas se pueden generar automáticamente utilizando el signo # al principio de cada elemento o enumerarlas manualmente (1, 2, 3…).

Ejemplo

Esta es una lista con viñetas.
Tiene dos ítems, el segundo item utiliza dos líneas.

Esta es una lista numerada.
También tiene dos elementos.
Esta es una lista numerada.
Tiene dos artículos también.

Estructura

* Esta es una lista con viñetas.
* Tiene dos ítems, el segundo item
  utiliza dos líneas.

1. Esta es una lista numerada.
2. También tiene dos elementos.

#. Esta es una lista numerada.
#. Tiene dos artículos también.

Listas anidadas#

Es posible anidar listas, pero es importante tener en cuenta que deben separarse de los elementos de la lista principal mediante líneas en blanco.

Ejemplo

Esto es
- una lista
- con una lista anidada
- y algunos subelementos
y aquí continúa la lista padre

Estructura

* Esto es
    * una lista
    * con una lista anidada
    * y algunos subelementos
* y aquí continúa la lista padre

Tablas#

Las tablas en reStructuredText se crean utilizando caracteres como la barra vertical |, guiones -, +, e incluso el signo igual = para definir las celdas y encabezados de la tabla.

Si desea mostrar tablas con bordes, deberá agregar la cuadrícula manualmente, por ejemplo:

Ejemplo

Fruta	Color	Sabor
Manzana	Roja	Dulce
Plátano	Amarillo	Dulce
Fresa	Roja	Dulce

Estructura

+-----------+--------------+------------+
| Fruta     | Color        | Sabor      |
+===========+==============+============+
| Manzana   | Roja         | Dulce      |
+-----------+--------------+------------+
| Plátano   | Amarillo     | Dulce      |
+-----------+--------------+------------+
| Fresa     | Roja         | Dulce      |
+-----------+--------------+------------+

Las tablas simples son más fáciles de escribir, pero tienen limitaciones. Deben tener más de una fila y las celdas de la primera columna no pueden contener múltiples líneas, por ejemplo:

Ejemplo

Fruta	Color	Sabor
Manzana	Roja	Dulce
Plátano	Amarillo	Dulce
Fresa	Roja	Dulce

Estructura

================  ==========  ==========
Fruta             Color       Sabor
================  ==========  ==========
Manzana           Roja        Dulce
Plátano           Amarillo    Dulce
Fresa             Roja        Dulce
================  ==========  ==========

Si necesita información más detallada acerca de las tablas, puede consultar la documentación disponible en Tables .

Hipervínculos#

Enlaces externos#

Puede crear hipervínculos a sitios externos de dos maneras sencillas, utilizando una función especial de reST o empleando código HTML.

Para utilizar la función que ofrece reST, puede hacerlo de la siguiente manera:

Ejemplo

Documentación oficial de Sphinx .

Estructura

`Documentación oficial de Sphinx <https://www.sphinx-doc.org/en/master/>`_.

Importante

Tenga en cuenta que debe existir un espacio entre el texto del enlace y la apertura < de la URL.

Nota

Se recomienda el uso del Icons para destacar al usuario que se trata de un enlace.

La función que ofrece reST está está limitada y no hay un atributo que permita abrir el enlace en una nueva página por defecto. Si necesita esta funcionalidad, considere el uso de HTML de la siguiente manera:

Ejemplo

Documentación oficial de Sphinx .

Estructura

Establezca la etiqueta#

.. |nombre_etiqueta| raw:: html

    <a href="https://www.sphinx-doc.org/en/master" target="_blank">Documentación oficial de Sphinx</a>

Haga referencia a la etiqueta#

|nombre_etiqueta| :octicon:`report;1em;sd-text-info`.

Observe que simplemente debe crear una etiqueta HTML con el atributo target seguido del nombre que necesita, para después llamarla entre símbolos de barra.

Nota

Si utiliza enlaces externos con ayuda de HTML, se recomienda colocar las ligas al final de su documento rst y especificar que se trata de ligas externas mediante un comentario. Esto facilita una mejor organización y permite un mantenimiento más efectivo en posteriores ocasiones.

Enlaces internos#

Si desea enlazar a otra parte de su propia documentación, puede hacerlo utilizando dos funciones especiales de reST proporcionada por Sphinx.

Para que la función de reST opere correctamente, los nombres de las etiquetas deben ser únicos. Si coloca una etiqueta directamente antes del título de una sección, esta función tomará ese nombre por defecto y lo mostrará; es decir, no podrá modificar el nombre que quiera presentar. Por ejemplo:

Ejemplo

Se refiere a la sección misma, ver Enlaces internos .

Estructura

Establezca la etiqueta#

.. _mi-etiqueta-de-referencia:

Enlaces internos
----------------

Haga referencia a la etiqueta#

Se refiere a la sección misma :ref:`mi-etiqueta-de-referencia` :octicon:`report;1em;sd-text-info`.

Importante

Las etiquetas de referencia deben comenzar con un guion bajo.

Al hacer referencia a una etiqueta, se debe omitir el guion bajo.

Si necesita información más detallada acerca de hipervínculos, puede consultar la documentación disponible en reStructuredText .

La otra opción de hipervínculo interno es utilizando etiquetas personalizadas, como se muestra a continuación:

Ejemplo

Se refiere a la sección misma, ver Personaliza

Estructura

Establezca la etiqueta#

.. _etiqueta:

Enlaces internos
----------------

Haga referencia a la etiqueta#

Se refiere a la sección misma, ver `Personaliza <#etiqueta>`_ :octicon:`report;1em;sd-text-info`

Importante

Esta función es más cómoda y permite personalizar el mensaje del hipervínculo. El nombre de la etiqueta debe ser una sola palabra; no puede incluir espacios, por ejemplo, nombre_etiqueta debe ser etiqueta.

Directivas#

Las directivas son comandos especiales de marcado que permiten incorporar elementos interactivos, como tablas, imágenes, notas y otros elementos, en su documentación.

Básicamente, una directiva consta de un nombre, argumentos, opciones y contenido. Una directiva es uno de los mecanismos de extensión de reStructuredText (reST), y Sphinx la emplea de manera frecuente en su funcionamiento.

Tabla de contenidos#

Dado que reST no proporciona facilidades para interconectar varios documentos o dividir documentos en múltiples archivos de salida, Sphinx utiliza una directiva personalizada para agregar relaciones entre los distintos archivos que componen la documentación, así como tablas de contenidos. La directiva toctree es el elemento central en este proceso.

toctree#

La directiva toctree en reStructuredText (reST) se utiliza para crear una tabla de contenidos en su documentación. Permite especificar qué documentos o secciones se incluirán en la tabla de contenidos y la profundidad máxima de la jerarquía de secciones que se mostrará.

Inicio de la directiva toctree

Para comenzar a usar la directiva toctree, debe insertar .. toctree:: en su documento. Esta línea inicia la directiva y le dice a reST que se creará una tabla de contenidos en ese punto.

Parámetros

:caption:: Se utiliza para agregar un título o una leyenda a la tabla de contenidos generada por esa directiva.

Esto es útil cuando necesita proporcionar una breve descripción o contexto para la tabla de contenidos que está creando, por ejemplo:

.. toctree::
    :caption: Documentación de Python

    introduccion.rst
    variables.rst
    funciones.rst
    ...

:maxdepth:: Es un parámetro opcional, se utiliza para limitar la profundidad de la tabla de contenidos. Esto es útil si desea mostrar solo ciertos niveles de secciones.

Por ejemplo, :maxdepth: 2 mostrará solo las dos primeras capas de secciones en la tabla de contenidos:

.. toctree::
    :maxdepth: 2

    archivo1.rst
    archivo2.rst

:titlesonly:: Este parámetro resulta útil cuando se desea mostrar únicamente los títulos de las secciones en la tabla de contenidos, sin incluir enlaces.

Por ejemplo:

.. toctree::
    :titlesonly:

    archivo1.rst
    archivo2.rst

:hidden:: Si necesita que la tabla de contenidos se genere, pero no se muestre en la documentación final, puede utilizar hidden. Esto es útil para mantener la tabla de contenidos en segundo plano.

Observe el siguiente ejemplo:

.. toctree::
    :hidden:

    archivo1.rst
    archivo2.rst

:numbered:: Este parámetro es opcional y se utiliza para numerar automáticamente las entradas de la tabla de contenidos.

Por ejemplo, para que las entradas se numeren utilice el siguiente ejemplo:

.. toctree::
    :numbered:

    archivo1.rst
    archivo2.rst

Antes de continuar, asegúrese de tener en cuenta la ubicación de sus archivos. En este ejemplo, tenemos dos archivos en nuestro proyecto y dos archivos en carpetas diferentes.

.. toctree::

    Capitulo1.rst
    Capitulo2.rst
    Subcarpeta/Subcapitulo1.rst
    Subcarpeta/Subcapitulo2.rst

Importante

Asegúrese de aplicar la sangría de manera adecuada.

Correcto#

.. toctree::
    :maxdepth: 2
    :titlesonly:
    :numbered:

    Capitulo1.rst
    Capitulo2.rst
    Subcarpeta/Subcapitulo1.rst
    Subcarpeta/Subcapitulo2.rst

Incorrecto#

.. toctree::
:maxdepth: 2
:titlesonly:
:numbered:

Capitulo1.rst
Capitulo2.rst
Subcarpeta/Subcapitulo1.rst
Subcarpeta/Subcapitulo2.rst

Observe el siguiente ejemplo. Con fines prácticos, en la siguiente figura se muestra la tabla de contenido del proyecto principal, la cual incluye :maxdepth: 2 y :titlesonly:.

Ejemplo

Estructura

==========================
Documentación de Linkaform
==========================

.. toctree::
    :maxdepth: 2
    :titlesonly:

    1.Introducción/Introducción
    2.Módulos/Módulos
    3.PDF/PDF
    4.Reportes/Reportes
    5.Desarrolladores/Index
    Contribución/Index

En este ejemplo, hemos utilizado :maxdepth: 4 para mostrar las secciones hasta una profundidad de 4, :titlesonly: para visualizar solo los títulos, y :numbered: para numerar automáticamente el contenido.

Ejemplo

Estructura

==========================
Documentación de Linkaform
==========================

.. toctree::
    :maxdepth: 4
    :titlesonly:
    :numbered:

    1.Introducción/Introducción
    2.Módulos/Módulos
    3.PDF/PDF
    4.Reportes/Reportes
    5.Desarrolladores/Index
    Contribución/Index

Si requiere información adicional, conocer otros parámetros o necesita otros ejemplos puede consultar la documentación de Sphinx .

Preparar toctree#

Cuando tenga su contenido organizado y escrito en archivos .rst, debe indicarle a Sphinx dónde debe buscar los documentos. A continuación, siga los siguientes pasos para agregar su contenido al índice.

Nota

Para el siguiente ejemplo, tenga en cuenta que se está presentando un proyecto almacenado en la carpeta Desarrollador. En consecuencia, este ya se encuentra en el índice principal, por lo tanto, se mostrará como llamarla en el índice de dicha carpeta. Sin embargo, en caso de tener un proyecto independiente, los mismos pasos aplican.

Anteriormente, se mostró cómo y dónde crear sus archivos .rst. Ahora deberá agregar un título a sus archivos. Esto es fundamental, ya que la directiva busca el título principal para incluirlo en el índice.
Una vez que haya añadido el título, deberá incluir la ruta de sus archivos en el index.rst de su proyecto.

Directory Tree

.
├── carpeta_ejemplo
   ├── archivo1.rst
   ├── archivo2.rst
   ├── archivo3.rst
   ├── index.rst
   └── subcarpeta
       ├── archivo1.rst
       ├── archivo2.rst
       ├── archivo3.rst
       └── archivo4.rst

toctree en index.rst

==============
Título ejemplo
==============

.. toctree::

    archivo1
    archivo2
    archivo3
    subcarpeta/archivo1
    subcarpeta/archivo2
    subcarpeta/archivo3
    subcarpeta/archivo4

Ahora inserte la ruta del index de su proyecto en la carpeta padre del mismo, en este caso, el index de la carpeta Desarrollador.

Directory Tree

toctree en index.rst

==================================
Documentación para desarrolladores
==================================

.. toctree::
    :maxdepth: 1
    :titlesonly:

    Módulos/index
    PDF/index
    Reportes/index
    carpeta_ejemplo/index

Con esto, ha logrado insertar satisfactoriamente su contenido. Puede probar sus cambios siguiendo Generar documentación o continuar leyendo acerca de cómo escribir en reST.

Imágenes#

Las imágenes en línea se pueden definir utilizando la directiva image. El argumento obligatorio de esta directiva es la URI del archivo de imagen.

Opcionalmente, el bloque de la directiva de imagen puede contener una lista de campos clave y valor, que definen las opciones de la imagen, por ejemplo:

Ejemplo

Estructura

.. image:: /imgs/Contribución/gato.jpg
    :height: 650px
    :width: 550px
    :scale: 50%
    :alt: texto alternativo
    :align: center

Se reconocen las siguientes opciones:

Propiedad	Descripción
height	La altura deseada de la imagen en píxeles o porcentaje.
width	El ancho de la imagen en píxeles o porcentaje.
scale	El factor de escala uniforme de la imagen, expresado en porcentaje (el símbolo `%` es opcional).
alt	Texto alternativo.
align	La alineación de la imagen (`top`, `middle`, `bottom`, `left`, `center` o `right`).

Atención

Al utilizar la directiva image, debe tener en cuenta lo siguiente:

Es correcto que exista un espacio entre los dos puntos y la ruta de la imagen, así como también una sangría para las propiedades.

Correcto#

.. image:: /imgs/Contribución/gato.jpg
    :height: 300px
    :width: 550px
    :scale: 50%
    :alt: texto alternativo
    :align: center

Incorrecto#

.. image::/imgs/Contribución/gato.jpg
:height: 300px
:width: 550px
:scale: 50%
:alt: texto alternativo
:align: center

Si necesita más información sobre imágenes, puede consultar el siguiente enlace .

Bloques de código#

Los bloques de código son una herramienta valiosa que permite ver ejemplos de código, comprender su funcionamiento y en última instancia, aplicarlo a su propio proyecto. Sphinx proporciona una forma flexible de incluir bloques de código en su documentación a través de la directiva bloque de código.

Para mostrar un código de ejemplo, utilice code-block bajo la siguiente estructura:

.. code-block:: language

    code ...

Al especificar el lenguaje, se habilitarán los colores correspondientes a la sintaxis, como se muestra a continuación.

Código python

# Esto es un ejemplo de código en Python
def saludar(nombre):
    print("Hola, {nombre}!")

Código JS

// Esto es un ejemplo de código en JavaScript
function saludar(nombre) {
    console.log(`Hola, ${nombre}!`);
}
saludar("Pedrito");

Código HTML

<!-- Esto es un ejemplo de código HTML -->
<!DOCTYPE html>
<html>
<head>
    <title>Mi Página Web</title>
</head>
<body>
    <h1>Bienvenido a mi página web</h1>
    <p>Esta es una página de ejemplo.</p>
</body>
</html>

Código CSS

/*Esto es un ejemplo de código CSS*/
body {
    font-family: Arial, sans-serif;
    background-color: #f0f0f0;
    margin: 0;
    padding: 0;
}

.header {
    background-color: #333;
    color: #fff;
    text-align: center;
    padding: 10px;
}

.container {
    max-width: 800px;
    margin: 0 auto;
    padding: 20px;
}

Títulos dentro del bloque#

Puede agregar títulos dentro del bloque de código utilizando el parámetro :caption:`

.. code-block:: language
    :caption: Example

    code ...

Mostrar números de línea#

Puede agregar números de línea a bloques de código con el parámetro :linenos::

.. code-block:: language
    :linenos:

    code ...

Resaltar líneas#

Puede resaltar ciertas líneas utilizando el parámetro :emphasize-lines::

.. code-block:: language
    :emphasize-lines: 6,12,15

    code ...

Los parámetros mencionados anteriormente se reflejan de la siguiente manera, con un título, números de línea y líneas resaltadas:

Ejemplo de código XML#

<library>
<book>
    <title>El Gran Gatsby</title>
    <author>F. Scott Fitzgerald</author>
    <genre>Novela</genre>
    <published>1925</published>
</book>
<book>
    <title>1984</title>
    <author>George Orwell</author>
    <genre>Distopía</genre>
    <published>1949</published>
</book>
<book>
    <title>Matar a un ruiseñor</title>
    <author>Harper Lee</author>
    <genre>Novela</genre>
    <published>1960</published>
</book>
</library>

Si necesita explicar un fragmento de código en múltiples partes de la documentación o si el código es muy extenso, puede guardarlo en un archivo independiente y luego incluirlo de la siguiente manera:

.. include:: mi_codigo.txt

Nota

Para guardar su archivos, deberá ubicarlos en la carpeta codi dentro de la carpeta content.

Los parámetros mencionados anteriormente son los más utilizados. Si tiene alguna duda o necesita información adicional, consulte la documentación sobre code-block .

Código en crudo#

El código en crudo es un tipo de marcado sin formato. Se utiliza la directiva raw junto al lenguaje que va a ejecutar. Esta directiva funciona como una medida provisional que permite omitir el marcado de reStructuredText.

El siguiente ejemplo permite incrustar código HTML en crudo, es decir, se ejecutará como un HTML normal en un navegador.

HTML en crudo

Document

Fantasma

Estructura raw

.. raw:: html

    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Document</title>
    </head>
    <body>
        <style>
            .ghost{
            block-size: 25rem;
            inline-size: 17.5rem;
            background-color: #de95d6;
            border-radius: 10rem 10rem 0 0;
            position: relative;
            }
            .ghost::before{
            content: '';
            position: absolute;
            inset-block-end: -3.5rem;
            background-color: transparent;
            color: transparent;
            inline-size: 5.9rem;
            block-size: 6rem;
            border-radius: 50%;
            box-shadow: 5.9rem 0, 11.6rem 0;
            }
            .eye{
            background-color: white;
            color: white;
            position: absolute;
            inset-inline-end: 1.5rem;
            inset-block-start: 5rem;
            inline-size: 5rem;
            block-size: 5rem;
            border-radius: 50%;
            box-shadow: -7rem 0;
            }
            .eye::before{
            content: '';
            inline-size: 2rem;
            block-size: 2rem;
            border-radius: 50%;
            inset-block-start: 1.5rem;
            inset-inline-end: .8rem;
            background-color: #0c63bf;
            color: #0c63bf;
            box-shadow: -7rem 0;
            position: absolute;
            }
        </style>
        <h2>Fantasma</h2>
        <div class="ghost">
            <div class="eye"></div>
        </div>
    </body>
    </html>

En caso de tener un archivo extenso puede utilizar la directiva file y adjuntar la URL de su archivo. Por ejemplo:

.. raw:: html
    :file: /cod/archivo.html

Nota

Para guardar su archivo HTML, deberá ubicarlo en la carpeta codi dentro de la carpeta content.

Prudencia

Tenga cuidado con el uso excesivo de la directiva en crudo. Al permitir la omisión del marcado de reStructuredText hace que su página sea menos portátil, afectando el formato y además, representa un potencial agujero de seguridad.

Para más detalles consulte la documentación sobre transferencia de datos sin procesar .

Comentarios#

En reStructuredText, los comentarios se crean utilizando el carácter de dos puntos ... Los comentarios son útiles para incluir notas, aclaraciones o información que no debe aparecer en la documentación final, pero que puede ser útil para los autores o colaboradores del documento.

Aquí hay un ejemplo de como crear comentarios en reST:

Ejemplo

Este es un párrafo normal.

Estructura

Este es un párrafo normal.

.. Este es un comentario que no se mostrará en la documentación final.
    Puede escribir cualquier cosa aquí, y se ignorará al generar la salida.

Atención

La correcta aplicación de la sangría es esencial para que los comentarios sean interpretados adecuadamente. Los comentarios deben tener la misma sangría que el texto.

Directorios#

Nota

El siguiente contenido no es propio de restructuredtext ni de una extensión de Sphinx.

Para ilustrar de forma gráfica la estructura de su proyecto, utilice la herramienta tree basada exclusivamente en sistemas Unix y Linux. Este comando muestra la organización de directorios y archivos en forma de árbol, lo que facilita la navegación y la comprensión de la estructura de datos en el sistema.

Por lo general, ya se encuentra instalado en la mayoría de las distribuciones de Linux. Para verificar si tree está instalado en su sistema, simplemente abra una terminal y ejecute:

tree --version

Si tree está instalado, verá la versión del programa. Si no está instalado, puede seguir estos pasos para instalarlo en Debian/Ubuntu:

Abra una terminal y ejecute:

sudo apt-get update
sudo apt-get install tree

En el caso de tener una distribución de Linux diferente, puede consultar la siguiente página para instalar la herramienta de acuerdo a su sistema operativo.

Nota

Si está utilizando un sistema operativo Windows y tiene instalado Git Bash, puede utilizar la terminal, ya que básicamente es una emulación del entorno Unix.

Comandos de tree#

Los comandos de tree permiten limitar la profundidad de visualización de los directorios. Hay variedad de comandos que puede consultar directamente en la terminal ejecutando:

man tree

Algunos de los comandos más usados son los siguientes.

Comando	Descripción
$ tree	Muestra directorios y ficheros.
$ tree -d	Muestra solo directorios.
$ tree -L X	Muestra hasta X directorios de profundidad.
$ tree -f	Muestra los archivos con su respectiva ruta.
$ tree -a	Muestra todos los archivos, incluidos los ocultos.
$ tree /	Muestra un árbol de todo nuestro sistema.
$ tree -ugh	Muestra los ficheros con su respectivo propietario (-u), el grupo (-g) y el tamaño de cada archivo (-h).
$ tree -H . -o nombre_archivo.html	Exporta el árbol del directorio a un archivo HTML.

Para crear un directorio siga los siguientes pasos.

Ubique la carpeta deseada, por ejemplo:
```
cd lkf/documentation
```
Ejecute el comando que necesite. En el siguiente ejemplo solo se muestran los directorios hasta el nivel 2.

Una vez confirmado su directorio exporte el archivo a html. Para ello ejecute:
```
-H . -o nombre_archivo.html
```

Importante

Al exportar su archivo HTML, por defecto se ubicará en la carpeta desde la cual esté consultando el directorio. Para evitar tener archivos HTML sueltos, deberá moverlo a la carpeta directorios. Asegúrese de darle un nombre descriptivo a su archivo.

Cuando tenga su directorio listo y desee colocarlo en un lugar específico, deberá hacer uso de Código en crudo y realizar algunas modificaciones necesarias.

El código html que se genera al exportar su directorio es el siguiente:

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="Author" content="Made by 'tree'">
<meta name="GENERATOR" content="$Version: $ tree v2.0.2 (c) 1996 - 2022 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro $">
<title>Directory Tree</title>
<style type="text/css">
BODY { font-family : monospace, sans-serif;  color: black;}
P { font-family : monospace, sans-serif; color: black; margin:0px; padding: 0px;}
A:visited { text-decoration : none; margin : 0px; padding : 0px;}
A:link    { text-decoration : none; margin : 0px; padding : 0px;}
A:hover   { text-decoration: underline; background-color : yellow; margin : 0px; padding : 0px;}
A:active  { margin : 0px; padding : 0px;}
.VERSION { font-size: small; font-family : arial, sans-serif; }
.NORM  { color: black;  }
.FIFO  { color: purple; }
.CHAR  { color: yellow; }
.DIR   { color: blue;   }
.BLOCK { color: yellow; }
.LINK  { color: aqua;   }
.SOCK  { color: fuchsia;}
.EXEC  { color: green;  }
</style>
</head>
<body>
    <h1>Directory Tree</h1><p>
    <a href=".">.</a><br>
    ├── <a href="./build/">build</a><br>
    │   ├── <a href="./build/Contribuci%C3%B3n/">Contribución</a><br>
    │   ├── <a href="./build/Desarrollador/">Desarrollador</a><br>
    │   ├── <a href="./build/_images/">_images</a><br>
    │   ├── <a href="./build/_sources/">_sources</a><br>
    │   ├── <a href="./build/_sphinx_design_static/">_sphinx_design_static</a><br>
    │   ├── <a href="./build/_static/">_static</a><br>
    │   └── <a href="./build/_video_thumbnail/">_video_thumbnail</a><br>
    ├── <a href="./content/">content</a><br>
    │   ├── <a href="./content/Contribuci%C3%B3n/">Contribución</a><br>
    │   ├── <a href="./content/Desarrollador/">Desarrollador</a><br>
    │   └── <a href="./content/imgs/">imgs</a><br>
    ├── <a href="./directorios/">directorios</a><br>
    ├── <a href="./extensions/">extensions</a><br>
    │   └── <a href="./extensions/cards/">cards</a><br>
    ├── <a href="./locale/">locale</a><br>
    │   └── <a href="./locale/en/">en</a><br>
    └── <a href="./static/">static</a><br>
    &nbsp;&nbsp;&nbsp; ├── <a href="./static/css/">css</a><br>
    &nbsp;&nbsp;&nbsp; └── <a href="./static/img/">img</a><br>
<br><br><p>

20 directories

</p>
    <hr>
    <p class="VERSION">
        tree v2.0.2 © 1996 - 2022 by Steve Baker and Thomas Moore <br>
        HTML output hacked and copyleft © 1998 by Francesc Rocher <br>
        JSON output hacked and copyleft © 2014 by Florian Sesser <br>
        Charsets / OS/2 support © 2001 by Kyosuke Tokoro
    </p>
</body>
</html>

Deberá realizar las siguientes modificaciones:

Elimine los estilos (líneas 8-24).
Elimine el H1 (línea 27).
Elimine los créditos (líneas 49-60).
En las etiquetas a elimine la URL de referencia.

Sus modificaciones se verán de la siguiente manera:

Directory Tree

Directory Tree .
├── build
│   ├── Contribución
│   ├── Desarrollador
│   ├── _images
│   ├── _sources
│   ├── _sphinx_design_static
│   ├── _static
│   └── _video_thumbnail
├── content
│   ├── Contribución
│   ├── Desarrollador
│   └── imgs
├── directorios
├── extensions
│   └── cards
├── locale
│   └── en
└── static
    ├── css
    └── img

Estructura

.. raw:: html

    <!DOCTYPE html>
    <html>
    <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta name="Author" content="Made by 'tree'">
    <meta name="GENERATOR" content="$Version: $ tree v2.0.2 (c) 1996 - 2022 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro $">
    <title>Directory Tree</title>
    </head>
    <body>
        <a>.</a><br>
        ├── <a>build</a><br>
        │   ├── <a>Contribución</a><br>
        │   ├── <a>Desarrollador</a><br>
        │   ├── <a>_images</a><br>
        │   ├── <a>_sources</a><br>
        │   ├── <a>_sphinx_design_static</a><br>
        │   ├── <a>_static</a><br>
        │   └── <a>_video_thumbnail</a><br>
        ├── <a>content</a><br>
        │   ├── <a>Contribución</a><br>
        │   ├── <a>Desarrollador</a><br>
        │   └── <a>imgs</a><br>
        ├── <a>directorios</a><br>
        ├── <a>extensions</a><br>
        │   └── <a>cards</a><br>
        ├── <a>locale</a><br>
        │   └── <a>en</a><br>
        └── <a>static</a><br>
        &nbsp;&nbsp;&nbsp; ├── <a>css</a><br>
        &nbsp;&nbsp;&nbsp; └── <a>img</a><br>
    </body>
    </html>

Para obtener más información sobre los comandos de tree, puede ejecutar el siguiente comando en su terminal:

man tree

En esta sección, ha aprendido a crear sus archivos con la estructura y contenido básico de restructuredtext. En la próxima sección, aprenderá a mejorar su contenido con la ayuda de extensiones que le proporcionarán un valor potencial más atractivo y funcional.

Escribiendo en reStructuredText#

Creación de archivo#

Secciones#

Párrafos#

Resaltos#

Listas#

Listas ordenadas y no ordenadas#

Listas anidadas#

Tablas#

Hipervínculos#

Enlaces externos#

Enlaces internos#

Directivas#

Tabla de contenidos#

toctree#

Preparar toctree#

Advertencias#

Nota#

Peligro#

Error#

Atención#

Advertencia#

Precaución#

Importante#

Pista#

Consejo#

Ver también#

Imágenes#

Bloques de código#

Títulos dentro del bloque#

Mostrar números de línea#

Resaltar líneas#

Código en crudo#

Fantasma

Comentarios#

Directorios#

Comandos de tree#