Diagramas y fórmulas¶

Diagramas¶

Dice el refrán que "una imagen vale por mil palabras". Y en cualquier documento, el uso de diagramas facilita la representación de ideas:

graph LR
  A[Inicio de la prueba] --> B{Error?};
  B -->|Si| C[Revisar...];
  C --> D[Verificar];
  D --> B;
  B ---->|No| E[Conseguido!];

Activar diagramas¶

Para lograr este resultado, tenemos que hacer uso de la extensión superfences, que ya hemos utilizado para mostrar texto de código fuente:

```clase

    texto de un programa

```

En este caso, en lugar de un lenguaje de programación vamos a utilizar un lenguaje de diagramas, basado en un proyecto llamado Mermaid, que es un software incorporado por Material for MkDocs. Tenemos que activarlo en mkdocs.yml:

- pymdownx.superfences:
    custom_fences:
      - name: mermaid
        class: mermaid
        format: !!python/name:pymdownx.superfences.fence_code_format

Uso¶

Siguiendo con el ejemplo anterior, allí donde queremos el diagrama, insertar el siguiente bloque en el texto markdown:

``` mermaid
graph LR
  A[Inicio de la prueba] --> B{Error?};
  B -->|Si| C[Revisar...];
  C --> D[Verificar];
  D --> B;
  B ---->|No| E[Conseguido!];
```

¿La sintaxis del lenguaje? Seguir la documentación de Mermaid. En cuanto a las reglas de estilo, colores, tipo de letra, etc, son las aportadas por Material for MkDocs y por las hojas de estilo añadidas por nosotros.

Existen varios tipos de diagramas. En el ejemplo, la primera línea del bloque indica el tipo:

graph LR

Veamos a continuación algunos ejemplos.

Diagrama de flujo¶

Un diagrama de flujo representa un proceso dividido en varios pasos. Cada paso es un nodo:

flowchart LR
  A[Inicio] --> B[Paso 1];
  B --> C[Paso 2];
  C --> D[Paso 3];
  D --> E[Final];
  E

Véase documentación. El tipo puede ser:

flowchart LR

o bien

graph LR

La palabra LR indica la dirección de las flechas:

TB - Top to bottom
TD - Top-down/ igual que top to bottom
BT - Bottom to top
RL - Right to left
LR - Left to right

Cada nodo se representa con un identificador y un texto entre corchetes, uniendo los diferentes pasos con -->

``` mermaid
graph LR
  A[Inicio] --> B[Paso 1];
  B --> C[Paso 2];
  C --> D[Paso 3];
  D --> E[Final];
  E 
```

Una nodo en forma de rombo se obtiene sustituyendo los corchetes por llaves {}. El texto superpuesto en las flechas se obtiene mediante:

nodo1 --> |texto| nodo2

Por ejemplo:

``` mermaid
graph LR
  A[Inicio] --> C{Comprobar};

  C --> |Ok| P2[Paso 2];
  P2 --> P3[Paso 3];
  P3 --> F[Final];

  C --> |Error| AB[Abortar];
  AB --> F[Final];
```

Muestra:

graph LR
  A[Inicio] --> C{Comprobar};

  C --> |Ok| P2[Paso 2];
  P2 --> P3[Paso 3];
  P3 --> F[Final];

  C --> |Error| AB[Abortar];
  AB --> F[Final];

Los nodos pueden tener diferente aspecto: rectángulos, círculos, rombos, etc. Ver documentación

Diagramas de secuencia¶

Los diagramas de secuencia describen una interacción entre múltiples objetos o personas:

sequenceDiagram
    Alicia->>Roberto: Hola Roberto, ¿que tal estás?
    Roberto->>Alicia: Bien, gracias ¿Y tu?
    create participant Carlos
    Alicia->>Carlos: ¡Hola Carlos!
    create actor D as Enrique
    Carlos->>D: ¡Hola!
    destroy Carlos
    Alicia-xCarlos: Somos demasiados
    destroy Roberto
    Roberto->>Alicia: Estoy de acuerdo

Siendo el texto fuente de este ejemplo:

```mermaid
sequenceDiagram
    Alicia->>Roberto: Hola Roberto, ¿que tal estás?
    Roberto->>Alicia: Bien, gracias ¿Y tu?
    create participant Carlos
    Alicia->>Carlos: ¡Hola Carlos!
    create actor D as Enrique
    Carlos->>D: ¡Hola!
    destroy Carlos
    Alicia-xCarlos: Somos demasiados
    destroy Roberto
    Roberto->>Alicia: Estoy de acuerdo
```

Véase como Mermaid proporciona un lenguaje de programación para representar con pocas líneas situaciones complejas. Ver referencia.

Diagramas de estado¶

Los diagramas de estado permiten describir el comportamiento de un sistema:

stateDiagram-v2
  state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> Estado1
    fork_state --> Estado2

    state join_state <<join>>
    Estado1 --> join_state
    Estado2 --> join_state
    join_state --> Estado4
    Estado4 --> [*]

Texto fuente:

``` mermaid
stateDiagram-v2
  state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> Estado1
    fork_state --> Estado2

    state join_state <<join>>
    Estado1 --> join_state
    Estado2 --> join_state
    join_state --> Estado4
    Estado4 --> [*]
```

Ver referencia

Diagramas de clases¶

En el mundo de la programación informática se usa una técnica denominada programación orientada a objetos. Cada aplicación está formada por objetos, que tienen unas propiedades, y estas dependen de la clase de objeto. Por ejemplo, toda persona pertenece a la clase "Persona", y como tal tiene unas propiedades de edad, sexo, nombre, apellidos, etc.

La clase a la que pertenece un objeto define las propiedades, las acciones que podemos realizar con los objetos, y las relaciones entre clases. Todo esto se puede representar gráficamente con diagramas de clases.

Supongamos una apliación informática que maneja cuatro clases de objetos:

personas
estudiantes
profesores
direcciones postales

Los objetos de la clase estudiante y profesor se relacionan con la clase persona, en la medida que tienen todas sus propiedades mas otras añadidas. Por lo tanto, en el diagrama representaremos:

la clase persona con sus atributos
las clases estudiante y profesor solo con los atributos añadidos que les son propios.

Además, la clase persona incluye un atributo dirección postal, que se relaciona con la clase direcciones. Cada dirección tiene, a su vez, otros atributos.

Cada clase se representa en un recuadro, indicando sus atributos y acciones previstas por la aplicación. El gráfico muestra también las relaciones entre clases:

classDiagram
  Persona <|-- Estudiante
  Persona <|-- Profesor
  Persona : +String nombre
  Persona : +String teléfono
  Persona : +String email
  Persona: +adquirirPase()
  Dirección "1" <-- "0..1" Persona:vive en
  class Estudiante{
    +int código
    +int notaMedia
    +Aprobar()
    +Suspender()
  }
  class Profesor{
    +int salario
  }
  class Dirección{
    +String calle
    +String ciudad
    +String provincia
    +int codigoPostal
    +String pais
    -validar()
    +crearFormatoTexto()  
  }

El texto fuente del gráfico es:

``` mermaid
classDiagram
  Persona <|-- Estudiante
  Persona <|-- Profesor
  Persona : +String nombre
  Persona : +String teléfono
  Persona : +String email
  Persona: +adquirirPase()
  Dirección "1" <-- "0..1" Persona:vive en
  class Estudiante{
    +int código
    +int notaMedia
    +Aprobar()
    +Suspender()
  }
  class Profesor{
    +int salario
  }
  class Dirección{
    +String calle
    +String ciudad
    +String provincia
    +int codigoPostal
    +String pais
    -validar()
    +crearFormatoTexto() 
  }
```

Ver referencia

Otros gráficos¶

Mermaid proporciona otros muchos tipos de gráficos, aunque su uso está condicionado por las hojas de estilo proporcionadas por Material for MkDocs, que no cubre todas las opciones. Véase documentación para más información.

Fórmulas aritméticas¶

La extensión Arithmatex genera y muestra ecuaciones matemáticas. En formato markdown, las fórmulas se escriben como bloque aparte delimitados entre dos marcas $$. Por ejemplo:

$$
\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
$$

Lo que se visualiza es lo siguiente:

\[ \cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k} \]

Arithmatex utiliza un software llamado MathJax. Consultar la documentación para conocer la sintaxis en la escritura de fórmulas.

Activar esta extensión con:

markdown_extensions:
   - pymdownx.arithmatex:
         generic: true

Además de activar la extensión, en el archivo de configuración mkdocs.yml debemos incluir:

extra_javascript:
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
  - javascripts/mathjax.js

Ya hemos visto que podemos poner un poco de programación en nuestra página web, usando el lenguaje javaScript. El parámetro de configuración extra_javascript permite indicar una lista de archivos script:

le decimos que incorpore un archivo online
añadimos nuestra propia pieza de programación, /docs/javascripts/mathjax.js

Tenemos que hacer de programadores informáticos y crear ese archivo mathjax.js Puede que no sepamos mucho sobre el lenguaje de programación JavaScript, pero da igual. El contenido del fichero es el siguiente texto:

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => { 
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

Usando KaTex¶

MathJax usa una sintaxis de escritura de fórmulas que puede resultar algo intimidante. Como alternativa, podemos utilizar KaTex, un software algo más sencillo.

En el archivo de configuración mkdocs.yml escribimos:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/katex.js
  - https://unpkg.com/katex@0/dist/katex.min.js
  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js

extra_css:
  - https://unpkg.com/katex@0/dist/katex.min.css

Y en la carpeta /docs/javascripts ponemos el siguiente archivo katex.js:

document$.subscribe(({ body }) => { 
  renderMathInElement(body, {
    delimiters: [
      { left: "$$",  right: "$$",  display: true },
      { left: "$",   right: "$",   display: false },
      { left: "\\(", right: "\\)", display: false },
      { left: "\\[", right: "\\]", display: true }
    ],
  })
})

Ver documentación de Material for MkDocs.