Personalización con extensiones#

En esta sección, aprenderá acerca de algunas de las extensiones que Sphinx proporciona para crear una documentación más atractiva.

Sphinx proporciona extensiones que no solo enriquecen la documentación técnica, sino que también hacen que el proceso de documentación sea más eficiente y efectivo. Al permitir la personalización y la automatización obtendrá documentación de alta calidad. Desde correcciones ortográficas, gráficos y ecuaciones complejas, cada extensión tiene su propia documentación detallada que proporciona instrucciones sobre cómo usarla y configurarla.

Las extensiones que se mostrarán a continuación ya se encuentran instaladas y listas para usar. No obstante, si necesita una extensión nueva, se proporcionarán los pasos de configuración dentro del entorno del proyecto.

Sphinxcontrib-mermaid#

Esta extensión le permite incrustar gráficos Mermaid en su documentación, incluidos diagramas de flujo, diagramas de secuencia, diagramas de Gantt y más.

Para hacer uso de mermaid, utilice la directiva .. mermaid::. Al crear diagramas, debe tener en cuenta las siguientes opciones de directivas.

Propiedad	Descripción
alt	Texto alternativo para la salida HTML.
align	Posición de la imagen. Opciones válidas: `left`, `center`, `right`.
caption	Título al diagrama.
zoom	Se utiliza para habilitar el zoom del diagrama (en caso de que sea muy grande).

En cuanto a los elementos que debe incluir un diagrama Mermaid, generalmente se utilizan:

Nodos: Representan elementos como procesos, decisiones, objetos, etc. Debe definir los nodos con un nombre único.
Conexiones: Las conexiones, se crean con –>, ==> o <–, indican la dirección en la que fluye la información o el proceso de un nodo a otro.
Etiquetas y Texto: Puede agregar etiquetas o texto a los nodos o conexiones para proporcionar información adicional o aclaraciones.
Estilos: Opcionalmente, puede aplicar estilos a los nodos y conexiones para personalizar la apariencia del diagrama, como colores, bordes y anchos de línea.

A continuación, se presentan algunos ejemplos que podrá utilizar. Tenga en cuenta que Mermaid es una herramienta muy flexible que le permitirá crear una amplia variedad de diagramas. Puede personalizar los diagramas según sus necesidades y documentar procesos, estructuras y relaciones de manera efectiva.

Diagrama de Flujo#

Los diagramas de flujo utilizan graph TD y graph TB. Puede usar graph TD para un flujo de arriba hacia abajo (Top-Down) y graph TB para un flujo de izquierda a derecha (Left-Right). Estos diagramas son ideales para representar flujos de trabajo, procesos y estructuras.

El siguiente ejemplo es un diagrama de flujo que representa un proceso con decisiones y ramificaciones.

Ejemplo 1

graph TB A(Inicio) --> B(Proceso 1) B --> C(Subproceso 1) B --> D(Subproceso 2) C --> E(Decisión 1) D --> F(Resultado 1) E --> G(Opción 1) E --> H(Opción 2) G --> I(Resultado 2) H --> I I --> J(Fin)

Estructura

.. mermaid::
    :alt: Ejemplo de diagrama de flujo
    :align: center
    :zoom:

    graph TB

        A(Inicio) --> B(Proceso 1)
        B --> C(Subproceso 1)
        B --> D(Subproceso 2)
        C --> E(Decisión 1)
        D --> F(Resultado 1)
        E --> G(Opción 1)
        E --> H(Opción 2)
        G --> I(Resultado 2)
        H --> I
        I --> J(Fin)

Otra forma de crear diagramas de flujo es a través de texto simple. De manera similar, utilice graph TD o graph TB. La principal diferencia entre el ejemplo anterior y este radica en la forma en que está organizado. En este caso, se emplea una especie de clases para aplicar nodos y conexiones, además de la posibilidad de aplicar estilos personalizados.

Ejemplo 2

graph TD %% Formularios form_solicitud_viaticos(#1 Solicitud de viáticos); form_autorizacion_viaticos(#3 Autorización de viáticos); form_entrega_anticipo_efectivo(#1.1 Entrega de anticipo efectivo); form_registros_gastos_viajes(#2 Registro de gastos de viaje); %% Catalogos catalogo_solicitud_gastos([Solicitud de gastos]); %% Conexiones form_solicitud_viaticos == status = pendiente autorización <br> ó gasto = 0 ==> form_autorizacion_viaticos; form_solicitud_viaticos == status = autorizado ==> form_entrega_anticipo_efectivo; form_entrega_anticipo_efectivo == status = autorizado <br> Actualiza ==> catalogo_solicitud_gastos; form_registros_gastos_viajes == Actualiza sets de gasto ==> form_solicitud_viaticos; form_registros_gastos_viajes == Monto actualizado - gasto ==> catalogo_solicitud_gastos; %% Estilos style form_solicitud_viaticos fill:#40c057,stroke:#333,stroke-width:1px; style form_autorizacion_viaticos fill:#40c057,stroke:#333,stroke-width:1px; style form_entrega_anticipo_efectivo fill:#40c057,stroke:#333,stroke-width:1px; style form_registros_gastos_viajes fill:#40c057,stroke:#333,stroke-width:1px; style catalogo_solicitud_gastos fill:#228be6,stroke:#333,stroke-width:1px;

Estructura

.. mermaid::
    :alt: Ejemplo de diagrama de flujo
    :align: center
    :zoom:

    graph TD

        %% Formularios
        form_solicitud_viaticos(#1 Solicitud de viáticos);
        form_autorizacion_viaticos(#3 Autorización de viáticos);
        form_entrega_anticipo_efectivo(#1.1 Entrega de anticipo efectivo);
        form_registros_gastos_viajes(#2 Registro de gastos de viaje);

        %% Catalogos
        catalogo_solicitud_gastos([Solicitud de gastos]);

        %% Conexiones
        form_solicitud_viaticos == status = pendiente autorización <br> ó gasto = 0 ==> form_autorizacion_viaticos;
        form_solicitud_viaticos == status = autorizado ==> form_entrega_anticipo_efectivo;
        form_entrega_anticipo_efectivo == status = autorizado <br> Actualiza ==> catalogo_solicitud_gastos;
        form_registros_gastos_viajes == Actualiza sets de gasto ==> form_solicitud_viaticos;
        form_registros_gastos_viajes == Monto actualizado - gasto ==> catalogo_solicitud_gastos;

        %% Estilos
        style form_solicitud_viaticos fill:#40c057,stroke:#333,stroke-width:1px;
        style form_autorizacion_viaticos fill:#40c057,stroke:#333,stroke-width:1px;
        style form_entrega_anticipo_efectivo fill:#40c057,stroke:#333,stroke-width:1px;
        style form_registros_gastos_viajes fill:#40c057,stroke:#333,stroke-width:1px;
        style catalogo_solicitud_gastos fill:#228be6,stroke:#333,stroke-width:1px;

Diagrama de Gantt#

Los diagramas de gantt hacen uso de gantt.

Este es un diagrama de Gantt, muestra una programación de tareas a lo largo del tiempo.

Ejemplo 3

gantt title Diagrama de Gantt dateFormat YYYY-MM-DD section Sección 1 Tarea 1 :a1, 2023-01-01, 7d Tarea 2 :after a1, 3d section Sección 2 Tarea 3 :2023-01-10, 2d Tarea 4 : 2d

Estructura

.. mermaid::
    :alt: Ejemplo de diagrama de Gantt
    :align: center
    :zoom:

    gantt

        title Diagrama de Gantt
        dateFormat YYYY-MM-DD
        section Sección 1
        Tarea 1 :a1, 2023-01-01, 7d
        Tarea 2 :after a1, 3d
        section Sección 2
        Tarea 3 :2023-01-10, 2d
        Tarea 4 : 2d

Diagrama de Clases#

Los diagramas de clase utilizan classDiagram para inciar.

Este es un diagrama de clases que muestra la herencia y las propiedades de las clases «Perro» y «Gato» en relación con la clase base «Animal».

Ejemplo 4

classDiagram class Animal { - nombre: string + obtenerNombre(): string } class Perro { + ladrar(): void } class Gato { + maullar(): void } Animal <|-- Perro Animal <|-- Gato

Estructura

.. mermaid::
    :alt: Ejemplo de diagrama de Clases
    :align: center
    :zoom:

    classDiagram

        class Animal {
            - nombre: string
            + obtenerNombre(): string
        }
        class Perro {
            + ladrar(): void
        }
        class Gato {
            + maullar(): void
        }
        Animal <|-- Perro
        Animal <|-- Gato

Diagrama de Secuencia#

Los diagramas de secuencia empiezan por sequenceDiagram. Se utiliza para crear representar interacciones entre objetos o actores a lo largo del tiempo.

Ejemplo 5

sequenceDiagram participant dotcom participant iframe participant viewscreen dotcom->>iframe: Carga html con URL de iframe iframe->>viewscreen: Plantilla de solicitud viewscreen->>iframe: html & javascript iframe->>dotcom: iframe listo dotcom->>iframe: Establecer datos mermaid en iframe iframe->>iframe: Render mermaid

Estructura

.. mermaid::
    :alt: Ejemplo de diagrama de Secuencia
    :align: center
    :zoom:

    sequenceDiagram
        participant dotcom
        participant iframe
        participant viewscreen
        dotcom->>iframe: Carga html con URL de iframe
        iframe->>viewscreen: Plantilla de solicitud
        viewscreen->>iframe: html & javascript
        iframe->>dotcom: iframe listo
        dotcom->>iframe: Establecer datos mermaid en iframe
        iframe->>iframe: Render mermaid

Si necesita conocer más acerca de mermaid puede consultar la documentación Sphinxcontrib-mermaid .

Sphinx.ext.graphviz#

Esta extensión le permite representar información estructural como diagramas de redes y gráficos abstractos. Graphviz tiene muchas funciones útiles para diagramas concretos, como opciones de colores, fuentes, diseños de nodos tabulares, estilos de línea, hipervínculos y formas personalizadas.

A diferencia de Sphinxcontrib-mermaid, Graphviz utiliza un lenguaje de descripción llamado DOT, que es un lenguaje declarativo para describir gráficos y diagramas. Es más estructurado y complejo que el formato de texto plano de Mermaid. Una de las ventajas de utilizar graphviz, es la flexibilidad de controlar el formato de salida utilizando graphviz_output_format = 'png' en el Archivo conf.py.

Para hacer uso de graphviz, debe utilizar la directiva .. graphviz::. De la misma manera, tenga en cuenta las siguientes directivas.

Propiedad	Descripción
alt	Texto alternativo.
align	Alineación del gráfico (`left`, `center`, `right`).
caption	Título del gráfico.
name	Etiqueta.
class	Nombres de clase (una lista de clases separados por espacios) ver más .
layout	Tipo de gráfico. Especifica el nombre del motor de diseño .

Graphviz utiliza atributos para darle un aspecto visual a sus nodos, conexiones, fondos, etc., de manera similar a aplicar estilos CSS en línea. Puede consultar la lista completa de atributos aquí .

A continuación, se presentan algunos ejemplos de Graphviz.

Clústeres#

Este pequeño ejemplo ilustra la característica de usar el punto para dibujar nodos y bordes en grupos o regiones de diseño rectangulares separadas. Los grupos están codificados como subgrafos cuyos nombres tienen el prefijo clúster .

Ejemplo 1

$digraph G { fontname="Helvetica,Arial,sans-serif" node [fontname="Helvetica,Arial,sans-serif"] edge [fontname="Helvetica,Arial,sans-serif"] subgraph cluster_0 { style=filled; color=lightgrey; node [style=filled,color=white]; a0 -> a1 -> a2 -> a3; label = "process #1"; } subgraph cluster_1 { node [style=filled]; b0 -> b1 -> b2 -> b3; label = "process #2"; color=blue } start -> a0; start -> b0; a1 -> b3; b2 -> a3; a3 -> a0; a3 -> end; b3 -> end; start [shape=Mdiamond]; end [shape=Msquare]; }$

Estructura

.. graphviz::
    :align: center

    digraph G {
        fontname="Helvetica,Arial,sans-serif"
        node [fontname="Helvetica,Arial,sans-serif"]
        edge [fontname="Helvetica,Arial,sans-serif"]

        subgraph cluster_0 {
            style=filled;
            color=lightgrey;
            node [style=filled,color=white];
            a0 -> a1 -> a2 -> a3;
            label = "process #1";
        }

        subgraph cluster_1 {
            node [style=filled];
            b0 -> b1 -> b2 -> b3;
            label = "process #2";
            color=blue
        }
        start -> a0;
        start -> b0;
        a1 -> b3;
        b2 -> a3;
        a3 -> a0;
        a3 -> end;
        b3 -> end;

        start [shape=Mdiamond];
        end [shape=Msquare];
    }

Colores parcialmente transparentes#

Este ejemplo ilustra el uso de colores parcialmente transparentes para nodo fillcolor y para graficar bgcolor.

Ejemplo 2

graph Transparency {
layout=neato
start=11 // empiric value to set orientation
bgcolor="#0000ff11"
node [shape=circle width=2.22 label="" style=filled]
5 [color="#0000ff80"]
6 [color="#ee00ee80"]
1 [color="#ff000080"]
2 [color="#eeee0080"]
3 [color="#00ff0080"]
4 [color="#00eeee80"]
1 -- 2 -- 3 -- 4 -- 5 -- 6 -- 1
}

Estructura

.. graphviz::
    :align: center

    graph Transparency {
        layout=neato
        start=11 // empiric value to set orientation
        bgcolor="#0000ff11"
        node [shape=circle width=2.22 label="" style=filled]
        5 [color="#0000ff80"]
        6 [color="#ee00ee80"]
        1 [color="#ff000080"]
        2 [color="#eeee0080"]
        3 [color="#00ff0080"]
        4 [color="#00eeee80"]
        1 -- 2 -- 3 -- 4 -- 5 -- 6 -- 1
    }

Gradient aplicados a una estructura de datos#

Demuestra una aplicación de gradientes para registrar nodos .

Ejemplo 3

digraph g {
fontname="Helvetica,Arial,sans-serif"
node [fontname="Helvetica,Arial,sans-serif"]
edge [fontname="Helvetica,Arial,sans-serif"]
graph [
rankdir = "LR"
bgcolor = "white:lightblue"
style="filled"
gradientangle = 270];
node [
fontsize = "16"
shape = "ellipse"
style="filled"
gradientangle=90
];
edge [
];
"node0" [
label = "<f0> 0x10ba8| <f1>"
shape = "record"
gradientangle="90"
fillcolor = "yellow:blue"
];
"node1" [
label = "<f0> 0xf7fc4380| <f1> | <f2> |-1"
shape = "record"
fillcolor = "blue:red"
gradientangle = 0
];
"node2" [
label = "<f0> 0xf7fc44b8| | |2"
shape = "record"
fillcolor = "brown:yellow"
gradientangle = 90
];
"node3" [
label = "<f0> 3.43322790286038071e-06|44.79998779296875|0 | <f1>"
shape = "record"
fillcolor = "green:red"
gradientangle = 90
];
"node4" [
label = "<f0> 0xf7fc4380| <f1> | <f2> |2"
shape = "record"
fillcolor = "red:green"
gradientangle = 0
];
"node5" [
label = "<f0> (nil)| | |-1"
shape = "record"
fillcolor = "red:red"
gradientangle = 90
];
"node6" [
label = "<f0> 0xf7fc4380| <f1> | <f2> |1"
shape = "record"
fillcolor = "orange:green"
];
"node7" [
label = "<f0> 0xf7fc4380| <f1> | <f2> |2"
shape = "record"
fillcolor = "cyan:green"
];
"node8" [
label = "<f0> (nil)| | |-1"
shape = "record"
fillcolor = "cyan:cyan"
];
"node9" [
label = "<f0> (nil)| | |-1"
shape = "record"
fillcolor = "orange:orange"
gradientangle = 90
];
"node10" [
label = "<f0> (nil)| <f1> | <f2> |-1"
shape = "record"
fillcolor = "magenta:green"
];
"node11" [
label = "<f0> (nil)| <f1> | <f2> |-1"
shape = "record"
fillcolor = "red:green"
];
"node12" [
label = "<f0> 0xf7fc43e0| | |1"
shape = "record"
fillcolor = "magenta:magenta"
];
"node0":f0 -> "node1":f0 [
id = 0
];
"node0":f1 -> "node2":f0 [
id = 1
];
"node1":f0 -> "node3":f0 [
id = 2
];
"node1":f1 -> "node4":f0 [
id = 3
];
"node1":f2 -> "node5":f0 [
id = 4
];
"node4":f0 -> "node3":f1 [
id = 5
];
"node4":f1 -> "node6":f0 [
id = 6
];
"node4":f2 -> "node10":f0 [
id = 7
];
"node6":f0 -> "node3":f1 [
id = 8
];
"node6":f1 -> "node7":f0 [
id = 9
];
"node6":f2 -> "node9":f0 [
id = 10
];
"node7":f0 -> "node3":f1 [
id = 11
];
"node7":f1 -> "node1":f0 [
id = 12
];
"node7":f2 -> "node8":f0 [
id = 13
];
"node10":f1 -> "node11":f0 [
id = 14
];
"node10":f2 -> "node12":f0 [
id = 15
];
"node11":f2 -> "node1":f0 [
id = 16
];
}

Estructura

.. graphviz::
    :align: center

    digraph g {
        fontname="Helvetica,Arial,sans-serif"
        node [fontname="Helvetica,Arial,sans-serif"]
        edge [fontname="Helvetica,Arial,sans-serif"]
        graph [
        rankdir = "LR"
        bgcolor = "white:lightblue"
        style="filled"
        gradientangle = 270];
        node [
        fontsize = "16"
        shape = "ellipse"
        style="filled"
        gradientangle=90
        ];
        edge [
        ];
        "node0" [
        label = "<f0> 0x10ba8| <f1>"
        shape = "record"
        gradientangle="90"
        fillcolor = "yellow:blue"
        ];
        "node1" [
        label = "<f0> 0xf7fc4380| <f1> | <f2> |-1"
        shape = "record"
        fillcolor = "blue:red"
        gradientangle = 0
        ];
        "node2" [
        label = "<f0> 0xf7fc44b8| | |2"
        shape = "record"
        fillcolor = "brown:yellow"
        gradientangle = 90
        ];
        "node3" [
        label = "<f0> 3.43322790286038071e-06|44.79998779296875|0 | <f1>"
        shape = "record"
        fillcolor = "green:red"
        gradientangle = 90
        ];
        "node4" [
        label = "<f0> 0xf7fc4380| <f1> | <f2> |2"
        shape = "record"
        fillcolor = "red:green"
        gradientangle = 0
        ];
        "node5" [
        label = "<f0> (nil)| | |-1"
        shape = "record"
        fillcolor = "red:red"
        gradientangle = 90
        ];
        "node6" [
        label = "<f0> 0xf7fc4380| <f1> | <f2> |1"
        shape = "record"
        fillcolor = "orange:green"
        ];
        "node7" [
        label = "<f0> 0xf7fc4380| <f1> | <f2> |2"
        shape = "record"
        fillcolor = "cyan:green"
        ];
        "node8" [
        label = "<f0> (nil)| | |-1"
        shape = "record"
        fillcolor = "cyan:cyan"
        ];
        "node9" [
        label = "<f0> (nil)| | |-1"
        shape = "record"
        fillcolor = "orange:orange"
        gradientangle = 90
        ];
        "node10" [
        label = "<f0> (nil)| <f1> | <f2> |-1"
        shape = "record"
        fillcolor = "magenta:green"
        ];
        "node11" [
        label = "<f0> (nil)| <f1> | <f2> |-1"
        shape = "record"
        fillcolor = "red:green"
        ];
        "node12" [
        label = "<f0> 0xf7fc43e0| | |1"
        shape = "record"
        fillcolor = "magenta:magenta"
        ];
        "node0":f0 -> "node1":f0 [
        id = 0
        ];
        "node0":f1 -> "node2":f0 [
        id = 1
        ];
        "node1":f0 -> "node3":f0 [
        id = 2
        ];
        "node1":f1 -> "node4":f0 [
        id = 3
        ];
        "node1":f2 -> "node5":f0 [
        id = 4
        ];
        "node4":f0 -> "node3":f1 [
        id = 5
        ];
        "node4":f1 -> "node6":f0 [
        id = 6
        ];
        "node4":f2 -> "node10":f0 [
        id = 7
        ];
        "node6":f0 -> "node3":f1 [
        id = 8
        ];
        "node6":f1 -> "node7":f0 [
        id = 9
        ];
        "node6":f2 -> "node9":f0 [
        id = 10
        ];
        "node7":f0 -> "node3":f1 [
        id = 11
        ];
        "node7":f1 -> "node1":f0 [
        id = 12
        ];
        "node7":f2 -> "node8":f0 [
        id = 13
        ];
        "node10":f1 -> "node11":f0 [
        id = 14
        ];
        "node10":f2 -> "node12":f0 [
        id = 15
        ];
        "node11":f2 -> "node1":f0 [
        id = 16
        ];
    }

Hay más contenido que puede explorar y probar. Consulte esta liga para obtener más información.

sphinxcontrib.youtube#

Esta extensión facilita la incorporación de videos de YouTube y Vimeo en su documentación. Toman un argumento único y obligatorio, que es la identificación del video:

.. youtube:: dQw4w9WgXcQ

.. vimeo:: 148751763

De forma predeterminada, el vídeo incrustado tiene un tamaño de contenido de 720p. Para configurar esto modifique los parámetros:

Propiedad	Descripción
URL	ID del video de YouTube (obligatorio).
aspect	Relación proporcional de un elemento entre su ancho y alto, por ejemplo (4:3).
width	Ancho.
height	Altura.
align	Alineación (puede ser `center`, `left`, `right`).
privacy_mode	Modo de privacidad.
url_parameters	Inicia el video en un momento específico (por ejemplo, «?start=43»).

Ejemplo

Estructura

.. youtube:: 4b0gzFXmtCk
    :aspect: 16:9
    :width: 640
    :height: 360
    :align: center
    :privacy_mode: enable_privacy_mode
    :url_parameters: ?start=0

Para obtener más información, consulte el enlace sobre sphinxcontrib-youtube .

Archivo conf.py#

El archivo conf.py es el archivo de configuración principal en Sphinx, contiene las configuraciones y ajustes específicos que controlan cómo se genera y se presenta la documentación.

Podrá encontrar el archivo en el primer nivel del repositorio. A continuación, se explicarán algunos aspectos importantes a tener en cuenta.

templates_path define la ubicación de la carpeta que contiene las plantillas (archivos de estilo que controlan la apariencia de la documentación).
exclude_patterns se utiliza para especificar patrones de exclusión, es decir, evita que ciertos archivos o carpetas se incluyan en la generación de la documentación.
language establece el idioma predeterminado de la documentación.
languages_names es utilizado para proporcionar al usuario la posibilidad de seleccionar el idioma de la documentación (aunque esta opción se encuentra deshabilitada y está en proceso).

Prudencia

No modificar.

Idioma y otras configuraciones#

templates_path = ['_templates']
exclude_patterns = []

language = 'es'
languages_names = {
    'en': 'EN',
    'es': 'ES',
    'fr': 'FR',
}

extension_dir define la ubicación del directorio extensions para contener extensiones de Sphinx personalizadas o de terceros.
sys.path.insert(0, str(extension_dir.absolute())) agrega la ruta al directorio extensions al principio de la lista de rutas del sistema (sys.path). Es útil si desea utilizar extensiones personalizadas o que no están instaladas de forma global.
extensions se utiliza para habilitar las extensiones en el proyecto. Si necesita instalar una extensión nueva, consulte la documentación de instalación de su extensión de preferencia y posteriormente colóquela aquí.
source_suffix especifica las extensiones de archivo que Sphinx debe considerar como fuentes de documentación. En este caso, Sphinx procesará archivos con las extensiones .rst y .md, lo que significa que puede escribir documentos de Sphinx en formato reStructuredText (.rst) o en formato Markdown (.md).

Nota

Aunque markdown es más simple y fácil de usar, se recomienda utilizar restructuredtext , ya que Sphinx fue originalmente diseñado para funcionar con rst y proporciona mayor soporte y estabilidad con funciones, extensiones y directivas.

Extensiones#

extension_dir = Path('extensions')
sys.path.insert(0, str(extension_dir.absolute()))
extensions = [
    'sphinx_design', #Extensión para componentes responsivos.
    'sphinxcontrib.youtube', #Extensión para incrustar videos youtube.
    'sphinxcontrib.mermaid', #Extensión que permite hacer uso de Mermaind (diagramas).
    'sphinx_copybutton', #Extensión que hace posible personalizar .. code-block::
    'sphinx.ext.graphviz', #Extensión sobre gráficos.
    'myst_parser',  #Extensión que permite a Sphinx leer MySt(Markedly Structured Text).
    'sphinx.ext.autodoc', #Automatizar la generación de documentación a partir de los comentarios y docstrings.
]
source_suffix = ['.rst', '.md']

html_theme es la configuración para especificar a Sphinx que se necesita utilizar el tema furo .
templates_path establece la ubicación del directorio de plantillas personalizadas que desea utilizar.
html_static_path es la ubicación de la carpeta static que contiene archivos estáticos, como imágenes y hojas de estilo, que se utilizarán en la documentación.

Importante

La carpeta static se encuentra en el primer nivel y está destinada a ser modificada. No debe confundirse con la que se encuentra en build.

html_css_files es la ubicacion del archivo custom.css para agregar CSS personalizado.
html_theme_options esta instrucción es muy importante, se utiliza para personalizar diferentes aspectos del tema furo, como la visibilidad del nombre en la barra lateral, los logotipos, colores, fuentes y otros detalles de estilo.

Prudencia

Cualquier cambio en html_theme_options afectará a todas las páginas de la documentación. No se recomienda modificarlo a menos que sea necesario.

pygments_style y pygments_dark_style establecen el estilo de resaltado de sintaxis para los bloques de código.
graphviz_output_format especifica el formato de salida para los gráficos generados con Graphviz. En este caso, los gráficos se generan en formato PNG.

Personalización y otras configuraciones#

html_theme = 'furo'
templates_path = ['./extensions/']
html_static_path = ['static']
html_css_files = ['css/custom.css']
html_theme_options = {
    'sidebar_hide_name': True,
    'light_logo': '/img/Linkaform_light.png',
    'dark_logo': '/img/Linkaform_dark_new.png',
    'light_css_variables': {
        "color-brand-primary": "#0c1c49",
        "color-brand-content": "#2c3e50",
        "color-background-hover": "#e1e2e6",
    },
    'dark_css_variables': {
        "color-background-primary": "#1c262d",
        "color-background-secondary": "#141b1f",
        "color-background-hover": "#27343e",
        "color-brand-primary": "#FFFFFF",
        "color-brand-content": "#E0E0E0",
        "color-header-text": "#FFFFFF",
    },
    'font-stack': "-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu",
}
pygments_style = "lightbulb"
pygments_dark_style = "zenburn"
graphviz_output_format = 'png'

¡Felicitaciones! 🎉 Si ha seguido la documentación secuencialmente, ahora es capaz de realizar contribuciones a Linkaform. Si tiene alguna duda, puede regresar al contenido o consultar la documentación oficial de la sección de su preferencia. También puede revisar la siguiente sección que aborda errores comunes.

Personalización con extensiones#

Sphinxcontrib-mermaid#

Diagrama de Flujo#

Diagrama de Gantt#

Diagrama de Clases#

Diagrama de Secuencia#

Sphinx.ext.graphviz#

Clústeres#

Colores parcialmente transparentes#

Gradient aplicados a una estructura de datos#

Sphinx_design#

Grids#

Cards#

Dropdowns#

Tabs#

Badges#

Buttons#

Icons#

sphinxcontrib.youtube#

Archivo conf.py#