Saltar a contenido

Dokumentador


Esta sección integra ejemplos de la herramienta de documentación rápida Dokumentador, que permite a partir de archivos de texto tipo Markdown generar de forma ágil y rápida documentación HTML en forma de un sitio web, documentos PDF y DOCX, este tipo de textos, es generada por la mayoría de informáticos para aquellas actividades, procesos, desarrollo, compilación, ensamblado, etc., que requieren ser documentados y se tiene poco tiempo para ello.

Creación de un proyecto  

Para iniciar con la documentación de un proyecto, basta estar dentro de la carpeta que contiene al proyecto a documentar y crear un archivo de configuración dokum.yml y una carpeta llamada docs, la estructura necesaria para un proyecto es:

dokum.yml      # Archivo de configuración del proyecto para su documentación
docs           # Carpeta que contiene la documentación tipo Markdown
docs/index.md  # Archivo de ejemplo de indice

Configuración  

El archivo dokum.yml contiene las entradas de configuración del Dokumentador:

Etiqueta Descripción
site_name Nombre del proyecto.
site_description Descripción del sitio.
site_dir Carpeta que salida de documentación generada.
docs_dir Carpeta que incluye los archivos de documentación a procesar.
theme Configuración del tema usado en la generación del Site y documentos.
nav Sección del layout de la documentación.

Ejemplo:

# Nombre del proyecto
site_name: Dokumentador Ejemplo
# Descripción del proyecto
site_description: Documentación Markdown para proyectos con Dokumentador.
# Carpeta que incluye los archivos de documentación a procesar
docs_dir: docs
# Carpeta que salida de documentación generada
site_dir: target/site

# Configuración del tema usado
theme:
    # Definición de colores
    palette:
        primary: teal
        accent: teal
    # Logo desplegado
    logo:  img/logo.svg
    # Icono de pagina
    favicon: img/favicon.ico

# Layout de la documentación
nav:
    - Inicio: index.md
    - Proyecto Ejemplo:
        - Manual: app/manual.md
        - Estructura: app/estructura.md
        - Requerimientos: app/requerimientos.md

Ajuste de Tema  

El Dokumentador utiliza un template genérico para construir el sitio Web y los archivos de documentos. Este template o tema permite hacer ciertas modificaciones para adecuar una generación con una imagen corporativa.

Icono  

El icono o favicon usado por el sitio Web se define en la etiqueta favicon, ejemplo:

theme:
    # Icono de pagina
    favicon: img/favicon.ico

Se permite incluir una imagen personalizada dentro de la documentación generada como logo corporativo, y está definida por la etiqueta logo:

theme:
    # Logo desplegado
    logo:  img/logo.svg

Colores  

Los colores usados por el tema del sitio están definidos por la sección palette, la cual tiene 2 opciones, los colores primarios primary y la de secundarios accent.

Para el caso de los colores primarios se tiene la siguiente lista y se puede hacer clic para cambiar el tema actual para probar:

Para los colores secundarios o de realce para algunos elementos se tiene la siguiente paleta:

Agregar contenidos  

Para agregar contenidos al site y la documentación generada, basta con crear archivos de texto con formato Markdown, estos con extensión .md, y agregarlo dentro del archivo de configuración dokum.yml, agregando el nuevo archivo dentro de la sección de nav como se muestra a continuación.

# Nombre del sitio del proyecto
site_name: Proyecto

# Layout de la documentación
nav:
    - Home: index.md
    - New: newPage.md   # Pagina nueva
    - About: about.md

Si se requiere más información sobre el proceso de documentación se puede consultar la página de Dokumentador.

Lenguaje Markdown

La documentación de cualquier proyecto en todos sus componentes es tardada, tortuosa y nunca se tiene tiempo suficiente, por lo anterior la mayoría de las veces sólo se documenta en archivos de texto TXT, para esto se inventó el lenguaje Markdown, que es un lenguaje muy ligero y que a partir de archivos de texto comunes, se puedan enriquecer y generar documentos más complejos.

Los archivos de texto tipo Markdown tiene una nomenclatura para crear los efectos en los contenidos como son: índices, tablas, recuadros, estilos, etc.; se recomienda leer los siguiente artículos para tener una mejor compresión del uso de este lenguaje a la hora de escribir la documentación.

Descargar Documentos  

La documentación generada ya incluye los archivos PDF y próximamente DOCX y sólo en caso de requerir combinar todos los PDFs del sitio, se requiere una utilería adicional, para descargar el archivo PDF hacer clic en el icono y para el DOCX en el icono .

Ejemplos

A continuación se muestran algunos de los ejemplos para la generación de documentos con el Dokumentador.

Secciones  

El Dokumentador permite crear y separar las secciones en nuestros documentos usando el estándar Markdown. Estas secciones son usadas para los accesos dinámicos o ligas dentro del sitio Web y archivos PDF & DOC .

Ejemplo de secciones:

1er Nivel encabezado

2o Nivel encabezado

3er Nivel encabezado

El encabezado más pequeño

Ejemplo de secciones:

# 1er Nivel encabezado
## 2o Nivel encabezado
### 3er Nivel encabezado
###### El encabezado más pequeño

Manejo de Texto  

El Dokumentador soporta el estándar Markdown para el manejo de los textos.

Markdown tiene las siguientes funciones básicas:

Texto Alterno Resultado
*Itálica* _Itálica_ Itálica
**Bold** __Bold__ Bold
**Bold _Itálica_** __Bold *Itálica*__ Bold Itálica
texto ==remarcado== texto remarcado
texto ~~tachado~~ texto tachado
texto `resaltado` texto resaltado
texto^\ superscript^ texto superscript
texto~\ subscript~ texto subscript
--- ***

También se permite el manejo de bloques de texto.

Ejemplo 1:

Bloque de texto 1

Ejemplo 2:

Bloque 2 Texto 2a linea

Ejemplo 3:

Bloque 3
Texto 2a linea

_Markdown_ tiene las siguientes funciones básicas:

Texto       | Alterno    |  Resultado
:--------------: | :-------------: | :-------------:
```*Italica*``` | ```_Italica_``` | _Italica_
```**Bold**```  | ```__Bold__``` | __Bold__
```texto ==remarcado==``` |    |  texto ==remarcado==
``` texto `resaltado` ``` |   | texto `resaltado`
```texto^\ superscript^``` |   | texto^\ superscript^
```texto~\ subscript~``` |   | texto~\ subscript~
```---```       | ```***``` |  ---

---

También se permite el manejo de bloques de texto.

Ejemplo 1:
>```
Bloque de texto 1
>```

Ejemplo 2:

>Bloque 2
>Texto 2a linea

Ejemplo 3:

    Bloque 3
    Texto 2a linea

Símbolos y Fórmulas  

El Dokumentador soporta la funcionalidad del manejo de Símbolos de Markdown:

Se permite uso de símbolos mediante la siguientes combinaciones de texto:

Texto Resultado Texto Resultado
(tm) <--
(c) © <-->
(r) ® =/=
c/o 1/4, etc. ¼, etc.
+/- ± 1st 2nd etc. 1st 2nd etc.
-->

Adicionalmente Dokumentador extiende esta funcionalidad y soporta el manejo de Fórmulas Matemáticas :

p(x|y) = \frac{p(y|x)p(x)}{p(y)}

Se permite uso de símbolos mediante la siguientes combinaciones de teto:

Texto       | Resultado    |  Texto       | Resultado
:------: |:------: | :------: | :------:
`(tm)`         | (tm)         |  `<--`          | <--
`(c)`          | (c)          |  `<-->`         | <-->
`(r)`          | (r)          |  `=/=`          | =/=
`c/o`          | c/o          |  `1/4, etc.`    | 1/4, etc.
`+/-`          | +/-          |  `1st 2nd etc.` |1st 2nd etc.
`-->`          | -->          |

---

El __Dokumentador__ extiende esta funcionalidad y soporta el manejo de [Fórmulas Matemática con (mathjax)][] :

\math {
    p(x|y) = \frac{p(y|x)p(x)}{p(y)}
}\math

Incluir

Markdown permite incluir elementos externos:

  • Contenido de archivos de texto Markdown:

    Este contenido es de un archivo externo de texto tipo Markdown


  • Imágenes locales:

Icono

  • Imágenes remotas:

Icono

- Contenido de archivos de texto `Markdown`:

{\!extras/dokum/test.md!}

---

- Imágenes locales:

![Icono](img/document.png)


- Imágenes remotas:

![Icono](http://iconbug.com/data/4d/64/9f5614cc92f4f1bb2de84cc6d9a6acd1.png)

Ligas

El manejo de Ligas o Links es soportado:

  • URLs relativos o a secciones de la misma página:

Textos

Ejemplos


  • URLs externo

Google

- URLs relativos o a secciones de la misma página:

[Textos](dokum.html#manejo_de_texto)

[Ejemplos](#ejemplos)

---

- URLs externo

[Google](https://www.google.com)

Listas

El soporte de Markdown permite el uso Listas o List en una forma simple.

  • Sección 1
  • Sección 2
  • Sección 3

  1. Numeral 1
  2. Numeral 2
  3. Numeral 3

  1. Primero
    • Segundo
      • Último

- Sección 1
- Sección 2
- Sección 3

---

1. Numeral 1
2. Numeral 2
3. Numeral 3

---

1. Primero
    - Segundo
        - Último

Lista de Tareas

Lista de Tareas o Task List.

  • item 1
    • item A
    • item B Texto adicional
      • item a
      • item b

- [X] item 1
    * [X] item A
    * [ ] item B
        Texto adicional
        + [x] item a
        + [ ] item b

Símbolos de Teclas

Se puede representar teclas y generar sus distintas combinaciones:

Por ejemplo el siguiente texto:

++ctrl+alt+delete++

++ctrl+a++

genera la siguiente representación:

CtrlAltDel

CtrlA

Los códigos de las teclas disponibles son:

Código Resultado Código Resultado
++"0"++ 0 ++"I"++ I
++"1"++ 1 ++"J"++ J
++"2"++ 2 ++"K"++ K
++"3"++ 3 ++"L"++ L
++"4"++ 4 ++"M"++ M
++"5"++ 5 ++"N"++ N
++"6"++ 6 ++"O"++ O
++"7"++ 7 ++"P"++ P
++"8"++ 8 ++"Q"++ Q
++"9"++ 9 ++"R"++ R
++"A"++ A ++"S"++ S
++"B"++ B ++"T"++ T
++"C"++ C ++"U"++ U
++"D"++ D ++"V"++ V
++"E"++ E ++"W"++ W
++"F"++ F ++"X"++ X
++"G"++ G ++"Y"++ Y
++"H"++ H ++"Z"++ Z
++"Space"++ Space ++"Backspace"++ Backspace
++"Del"++ Del ++"Ins"++ Ins
++"Break"++ Break ++"Caps Lock"++ Caps Lock
++"Clear"++ Clear ++"Eject"++ Eject
++"Enter"++ Enter ++"Esc"++ Esc
++"Help"++ Help ++"Print Screen"++ Print Screen
++"Scroll Lock"++ Scroll Lock ++tab++ Tab
++arrow-up++ Up ++arrow-left++ Left
++arrow-down++ Down ++arrow-right++ Right
++page-up++ Page Up ++home++ Home
++page-down++ Page Down ++end++ End
++"Num 0"++ Num 0 ++"Num *"++ Num *
++"Num 1"++ Num 1 ++"Num Clear"++ Num Clear
++"Num 2"++ Num 2 ++"Num Del"++ Num Del
++"Num 3"++ Num 3 ++"Num ="++ Num =
++"Num 4"++ Num 4 ++"Num Lock"++ Num Lock
++"Num 5"++ Num 5 ++"Num -"++ Num -
++"Num 6"++ Num 6 ++"Num \+"++ Num +
++"Num 7"++ Num 7 ++"Num ."++ Num .
++"Num 8"++ Num 8 ++"Num /"++ Num /
++"Num 9"++ Num 9 ++"Num Enter"++ Num Enter
++"Alt"++ Alt ++"Meta"++ Meta
++"Cmd"++ Cmd ++"Option"++ Option
++"Ctrl"++ Ctrl ++"Right Alt"++ Right Alt
++"Fn"++ Fn ++"Right Ctrl"++ Right Ctrl
++"Left Alt"++ Left Alt ++"Right Shift"++ Right Shift
++"Left Ctrl"++ Left Ctrl ++"Right Win"++ Right Win
++"Left Shift"++ Left Shift ++"Shift"++ Shift
++"Left Win"++ Left Win ++"Win"++ Win
++"F1"++ F1 ++"F13"++ F13
++"F2"++ F2 ++"F14"++ F14
++"F3"++ F3 ++"F15"++ F15
++"F4"++ F4 ++"F16"++ F16
++"F5"++ F5 ++"F17"++ F17
++"F6"++ F6 ++"F18"++ F18
++"F7"++ F7 ++"F19"++ F19
++"F8"++ F8 ++"F20"++ F20
++"F9"++ F9 ++"F21"++ F21
++"F10"++ F10 ++"F22"++ F22
++"F11"++ F11 ++"F23"++ F23
++"F12"++ F12 ++"F24"++ F24
++"\\"++ \ ++">"++ >
++"\|"++ | ++"<"++ <
++"{"++ { ++"-"++ -
++"}"++ } ++"."++ .
++"["++ [ ++"\+"++ +
++"]"++ ] ++"?"++ ?
++":"++ : ++";"++ ;
++","++ , ++"'"++ '
++"\""++ " ++"/"++ /
++"="++ = ++"~"++ ~
++"!"++ ! ++"_"++ _
++"\"++| ++"\"++

Estilos CSS

El Dokumentador permite definir un estilo CSS en una sección del texto deseado.

Para permitir un mejor ajuste en los textos se permiten estilos CSS, su formato es:

Texto
{: #id_cualquiera .nombre_de_clase_css llave='valor' }

Ejemplos:

Texto con clase 1.

Texto con clase 2.

Para permitir un mejor ajuste en los textos se permiten estilos __CSS__, su formato es:

```
Texto
{: #id_cualquiera .nombre_de_clase_css llave='valor' }
```

Ejemplos:

Texto con clase 1.
{: #IdPrueba .css_test }

Texto con clase 2.
{: #IdPrueba2 .css_test2}

Iconos Font Awesome  

Uso de Font Awesome 4 para el manejo de iconos en de los textos:

Se tienen 2 formas de para el manejo de fonts:

  1. Forma reducida :[(nombre del font) (clases extra)]::

fa-xs fa-lg fa-2x fa-3x fa-4x fa-5x

  1. Forma directa con HTML:

fa-xs fa-lg fa-2x fa-3x fa-4x fa-5x

Esta forma permite un manejo más avanzado de los fonts:

Se tienen 2 formas de para el manejo de fonts:

1. Forma reducida `:[(nombre del font) (clases extra)]:`:

:fa-github-square:
:fa-user fa-fw texto-sombra-1a:
:fa-user fa-fw sombra-1b:
:fa-spinner fa-spin fa-2x fa-fw:

:fa-camera-retro fa-xs: fa-xs
:fa-camera-retro fa-lg: fa-lg
:fa-camera-retro fa-2x: fa-2x
:fa-camera-retro fa-3x: fa-3x
:fa-camera-retro fa-4x: fa-4x
:fa-camera-retro fa-5x: fa-5x

2. Forma directa con HTML:

<i class="fa fa-github-square"></i>
<i class="fa fa-user fa-fw texto-sombra-1a"></i>
<i class="fa fa-user fa-fw sombra-1a"></i>
<i class="fa fa-spinner fa-spin fa-2x fa-fw"></i>

<i class="fa fa-camera-retro fa-xs"></i> fa-xs
<i class="fa fa-camera-retro fa-lg"></i> fa-lg
<i class="fa fa-camera-retro fa-2x"></i> fa-2x
<i class="fa fa-camera-retro fa-3x"></i> fa-3x
<i class="fa fa-camera-retro fa-4x"></i> fa-4x
<i class="fa fa-camera-retro fa-5x"></i> fa-5x

Esta forma permite un manejo más avanzado de los fonts:

<span class="fa-stack fa-lg">
    <i class="fa fa-square-o fa-stack-2x" style="color:red"></i>
    <i class="fa fa-twitter fa-stack-1x"></i>
</span>
<span class="fa-stack fa-lg">
    <i class="fa fa-circle fa-stack-2x"></i>
    <i class="fa fa-flag fa-stack-1x fa-inverse" style="color:cyan"></i>
</span>

Tablas

El manejo de tablas con Markdown es realmente fácil:

Sin centrar Izquierda Centrar Derecha
Celda 1 Celda 3 Celda 5 Celda 7
Celda 2 Celda 4 Celda 6 Celda 8
Celda 9 Celda 10 Celda 11 Celda 12

Adicionalmente al estándar Markdown, el Dokumentador agrega la funcionalidad de tablas dinámicas, esto con sólo anteponer al inicio de una tabla el siguiente token:

:table(nombre de la tabla, número de renglones, nombre de archivo exportar):

Ejemplo de una tabla dinámica:

Oficinas Servicios Empleados Apertura
Tokyo 21 02/06/2006
San Francisco 1 40 02/06/2006
San Francisco 2 14 02/06/2016
London 1 20 02/06/2006
London 2 10 02/06/2017
London 3 35 02/06/2018
New York 1 11 02/06/2009
New York 2 16 02/06/2011
New York 3 20 02/06/2014
Edinburgh 87 02/06/2010
México 1 32 02/06/2012
México 2 32 02/06/2017

| Sin centrar  | Izquierda | Centrar | Derecha
| ----------- |:----------|:----------:| --------:
| Celda  1 | Celda  3 | Celda  5 | Celda  7
| Celda  2 | Celda  4 | Celda  6 | Celda  8
| Celda  9 | Celda  10 | Celda  11 | Celda  12

Adicionalmente al estándar _Markdown_, el __Dokumentador__ agrega la funcionalidad de tablas dinámicas, esto con sólo anteponer al inicio de una tabla el siguiente token:

`:table(nombre de la tabla, número de renglones, nombre de archivo exportar)`:

Ejemplo de una tabla dinámica:

:table(tabla1, 5):

Oficinas       | Servicios                | Empleados    | Apertura
:-------------- |:------------------------:|:------------:|:----------:
Tokyo           | :fa-table fa-fw :         :fa-windows fa-fw : |     21       |  02/06/2006
San Francisco 1 | :fa-thermometer-2 fa-fw : :fa-linux fa-fw : |     40       | 02/06/2006
San Francisco 2 | :fa-calculator fa-fw :    |     14       |  02/06/2016
London   1      | :fa-bluetooth fa-fw :     :fa-apple fa-fw : |     20       | 02/06/2006
London   2      | :fa-car fa-fw :           |     10       |  02/06/2017
London   3      | :fa-microchip fa-fw :     :fa-linux fa-fw : |     35       | 02/06/2018
New York 1      | :fa-bus fa-fw :           |     11       |  02/06/2009
New York 2      | :fa-check fa-fw :         |     16       |  02/06/2011
New York 3      | :fa-calendar fa-fw :      |     20       |  02/06/2014
Edinburgh       | :fa-photo fa-fw :         |     87       |  02/06/2010
México 1        | :fa-plug fa-fw :          |     32       |  02/06/2012
México 2        | :fa-folder fa-fw :        |     32       |  02/06/2017

Código

El Dokumentador nos permite el poder incrustar secciones de código resaltado de distintos lenguajes para un mejor entendimiento si necesidad de capturas de pantalla.

  • Código en linea:

Sección de código en PHP: $a = array("foo" => 0, "bar" => 1);

Otro ejemplo en Java: List<String> lst = new ArrayList<>();

Sección de código en PHP:  `#!php-inline $a = array("foo" => 0, "bar" => 1);`

Otro ejemplo en Java:  `#!java-inline List<String> lst = new ArrayList<>();`

  • Código en bloques:

Python

import tensorflow as tf

Java

import org.java.String;
import org.java.List;

import foo.bar
import foo.bar2
import foo.bar
import boo.baz
import foo.bar.baz
import foo.bar.baz2

Python

```python
import tensorflow as tf
```

Java

```java
import org.java.String;
import org.java.List;
```

---


```java linenums="1"
import foo.bar
import foo.bar2
```


```java linenums="1" hl_lines="2 3"
import foo.bar
import boo.baz
import foo.bar.baz
import foo.bar.baz2
```

Pestañas

Se permite el uso de controles de pestañas tab para un mejor entendimiento de la documentación, esta funcionalidad sólo se recomienda para HTML.

Ejemplo 1:

#!/bin/bash
STR="Hello World!"
echo $STR
#include
int main(void) {
printf("hello, world\n");
}
#include <iostream>
int main() {
std::cout << "Hello, world!\n"; return 0;
}

Ejemplo 2:

pubic static void oneTest();
public static void twoTest();

Ejemplo 1:

```Bash linenums="1" tab=
#!/bin/bash
STR="Hello World!"
echo $STR
```

```C linenums="1" tab=
#include
int main(void) {
printf("hello, world\n");
}
```

```C++ linenums="1" tab=
#include &lt;iostream&gt;
int main() {
std::cout &lt;&lt; "Hello, world!\n"; return 0;
}
```

Ejemplo 2:

```java tab="One"
pubic static void oneTest();
```

```java tab="Two"
public static void twoTest();
```

Diálogos

Otro tipo de controles para la documentación, son los diálogos, lamentablemente no todos los navegadores de HTML lo soportan.

Información

Contenido de Información.

Aceptar

Contenido de Aceptar.

Nota

Contenido de Nota

Más tipos de diálogo

Ejemplo

Contenido de Ejemplo

Resumen

Contenido de Resumen.

Warning

Contenido de Warning.

Falla

Contenido de Falla

Peligro

Contenido de Peligro

Configuración

Contenido de Configuración

Tips

Contenido de Tips

Defecto

Contenido de Defecto

Pregunta

Contenido de Pregunta

Cita

Contenido de Cita

!!! info "Información"
    Contenido de Información.

??? success "Aceptar"
    Contenido de Aceptar.

!!! note "Nota"
    Contenido de Nota

??? summary "Más tipos de diálogo"

    !!! example "Ejemplo"
        Contenido de Ejemplo

    !!! summary "Resumen"
        Contenido de Resumen.

    ???+ warning classes
        Contenido de Warning.

    !!! failure "Falla"
        Contenido de Falla

    !!! danger "Peligro"
        Contenido de Peligro

    ??? settings "Configuración"
        Contenido de Configuración

    ???+ tip "Tips"
        Contenido de Tips

    ??? bug "Defecto"
        Contenido de Defecto

    ??? question "Pregunta"
        Contenido de Pregunta

    !!! quote "Cita"
        Contenido de Cita

Barras de Progreso

Hay controles de barras de progreso o Progress Bar para la documentación.

5%

25%

65%

85%

[=5% "5%"]
[=25% "25%"]
[=65% "65%"]
[=85% "85%"]
[=45%]{: .thin}
[=95%]{: .thin}

Gráficos

El Dokumentador introduce el manejo de distintos tipos de gráficos en una forma sencilla basados en el componente de generación Chart.js.

Lineas  

Soporta Gráficos de Lineas

Gráfico 1

Temporal Image

Gráfico 2

Temporal Image

Gráfico 1

\chart(id: 'chartLine1', width: '400', height: '400') {
    type: 'line',
    data: {
        labels: ['Ene', 'Feb', 'Mar', 'Abr', 'May', 'Jun', 'Jul'],
        datasets: [{
            label: 'Linea',
            fill: false,
            backgroundColor: "rgba(220,20,20,0.2)",
            borderColor: 'rgba(220,20,20,0.8)',
            data: [65, 59, 80, 81, 56, 55, 40],
        }, {
            label: 'Punteada',
            fill: false,
            backgroundColor: 'rgba(120,120,220,0.2)',
            borderColor: 'rgba(020,120,255,0.8)',
            borderDash: [5, 5],
            data: [28, 48, 40, 19, 86, 27, 90],
        }, {
            label: 'Area',
            fill: true,
            backgroundColor: "rgba(0, 150, 136,0.2)",
            borderColor: "rgba(0, 150, 136,0.8)",
            data: [18, 78, 35, 40, 26, 60, 35],
        }]
    },
    options: {
        responsive: true,
        title: {
            display: true,
            text: 'Gráfica de Linea'
        },
        tooltips: {
            mode: 'index',
            intersect: false,
        },
        hover: {
            mode: 'nearest',
            intersect: true
        },
        scales: {
            xAxes: [{
                display: true,
                scaleLabel: {
                    display: true,
                    labelString: 'Mes'
                }
            }],
            yAxes: [{
                display: true,
                scaleLabel: {
                    display: true,
                    labelString: 'Valores'
                }
            }]
        }
    }
}\chart

Gráfico 2

\chart(id: 'chartLine2', width: '100%', height: '100%') {
    type: 'line',
    data: {
        labels: ['Ene', 'Feb', 'Mar', 'Abr', 'May', 'Jun', 'Jul'],
        datasets: [{
            label: 'Muestra 1',
            backgroundColor: 'rgba(75, 192, 192, 0.5)',
            borderColor: 'rgba(75, 192, 192, 1)',
            borderWidth: 1,
            data: [-65, -29, 35, 81, 56, 15, -20],
        }, {
            label: 'Muestra 2',
            backgroundColor: 'rgba(255, 99, 132, 0.5)',
            borderColor: 'rgba(255,99,132,1)',
            borderWidth: 1,
            pointStyle: 'rectRot',
            pointRadius: 5,
            pointBorderColor: 'rgb(0, 0, 0)',
            data: [29,-15, -75, -18, -46, 5, 35],
        }]
    },
    options: {
        responsive: true,
        title: {
            display: true,
            text: 'Gráfica de Linea'
        },
        legend: {
            position: 'bottom',
            usePointStyle: true,
            labels: {
                usePointStyle: true,
            }
        },
        tooltips: {
            mode: 'index',
            intersect: false,
        },
        hover: {
            mode: 'nearest',
            intersect: true
        },
        scales: {
            xAxes: [{
                display: true,
                scaleLabel: {
                    display: true,
                    labelString: 'Mes'
                }
            }],
            yAxes: [{
                display: true,
                scaleLabel: {
                    display: true,
                    labelString: 'Valores'
                }
            }]
        }
    }
}\chart

Barras  

Soporte a Gráficos de Barras

Gráfico 1

Temporal Image

Gráfico 2

Temporal Image

Gráfico 1

\chart(id: 'chartBar1', width: '400', height: '400') {
    type: 'bar',
    data: {
        labels: ['Rojo', 'Azul', 'Amarillo', 'Verde', 'Morado', 'Naranja'],
        datasets: [{
            label: '# Votos',
            data: [12, 19, 3, 5, 2, 3],
            backgroundColor: [
                'rgba(255, 99, 132, 0.2)',
                'rgba(54, 162, 235, 0.2)',
                'rgba(255, 206, 86, 0.2)',
                'rgba(75, 192, 192, 0.2)',
                'rgba(153, 102, 255, 0.2)',
                'rgba(255, 159, 64, 0.2)'
            ],
            borderColor: [
                'rgba(255,99,132,1)',
                'rgba(54, 162, 235, 1)',
                'rgba(255, 206, 86, 1)',
                'rgba(75, 192, 192, 1)',
                'rgba(153, 102, 255, 1)',
                'rgba(255, 159, 64, 1)'
            ],
            borderWidth: 1
        }]
    },
    options: {
        scales: {
            yAxes: [{
                ticks: {
                    beginAtZero:true
                }
            }]
        }
    }
}\chart

Gráfico 2

\chart(id: 'chartBar2', width: '400', height: '400') {
    type: 'bar',
    data: {
        labels: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio', 'Julio'],
        datasets: [{
            label: 'Muestra 1',
            data: [12, 19, 3, 5, 2, 3, 6],
            backgroundColor: 'rgba(255, 99, 132, 0.8)',
            borderColor: 'rgba(255, 99, 132, 1)',
        }, {
            label: 'Muestra 2',
            data: [3, 4, 6, 8, 12, 7, 2],
            backgroundColor: 'rgba(54, 162, 235, 1)',
            borderColor: 'rgba(54, 162, 235, 1)',
        }, {
            label: 'Muestra 3',
            data: [4, 6, 7, 2, 8, 6, 12],
            backgroundColor: 'rgba(75, 192, 192, 1)',
            borderColor: 'rgba(75, 192, 192, 1)',
        }]
    },
    options: {
        title: {
            display: true,
            text: 'Gráfica de Barras Apiladas'
        },
        tooltips: {
            mode: 'index',
            intersect: false
        },
        responsive: true,
        legend: {
            position: 'bottom',
        },
        scales: {
            xAxes: [{
                stacked: true,
            }],
            yAxes: [{
                stacked: true
            }]
        }
    }
}\chart

Pie  

También se incluye soporte a Gráficos Circulares o tipo Pie.

Gráfico 1

Temporal Image

Gráfico 2

Temporal Image

Gráfico 1

\chart(id: 'chartPie1', width: '100%', height: '100%') {
    type: 'pie',
    data: {
        datasets: [{
            data: [12, 19, 23, 15, 32],
            backgroundColor: [
                'rgba(255, 99, 132, 0.8)',
                'rgba(255, 159, 64, 0.8)',
                'rgba(255, 206, 86, 0.8)',
                'rgba(75, 192, 192, 0.8)',
                'rgba(54, 162, 235, 0.8)',
            ],
            borderColor: [
                'rgba(255,99,132,1)',
                'rgba(255, 159, 64, 1)',
                'rgba(255, 206, 86, 1)',
                'rgba(75, 192, 192, 1)',
                'rgba(54, 162, 235, 1)',
            ],
            label: 'Dataset 1'
        }],
        labels: [
            'Rojo',
            'Naranja',
            'Amarillo',
            'Verde',
            'Azul'
        ]
    },
    options: {
        responsive: true,
        legend: {
            position: 'left',
        },
        title: {
            display: true,
            text: 'Gráfica en Pie'
        },
    }
}\chart

Gráfico 2

\chart(id: 'chartPie2', width: '100%', height: '100%') {
    type: 'doughnut',
    data: {
        datasets: [{
            data: [12, 19, 23, 15, 32],
            backgroundColor: [
                'rgba(255, 99, 132, 0.8)',
                'rgba(255, 159, 64, 0.8)',
                'rgba(255, 206, 86, 0.8)',
                'rgba(75, 192, 192, 0.8)',
                'rgba(54, 162, 235, 0.8)',
            ],
            borderColor: [
                'rgba(255,99,132,1)',
                'rgba(255, 159, 64, 1)',
                'rgba(255, 206, 86, 1)',
                'rgba(75, 192, 192, 1)',
                'rgba(54, 162, 235, 1)',
            ],
            label: 'Dataset 1'
        }],
        labels: [
            'Rojo',
            'Naranja',
            'Amarillo',
            'Verde',
            'Azul'
        ]
    },
    options: {
        responsive: true,
        legend: {
            position: 'right',
        },
        title: {
            display: true,
            text: 'Gráfica de Dona'
        },
    }
}\chart

Otros  

Otros gráficos que soporta son Polar, Radar y Combinados.

Polar

Temporal Image

Radar

Temporal Image

Combinados

Temporal Image

Polar

\chart(id: 'chartPolar1', width: '70%', height: '60%') {
    type: 'polarArea',
    data: {
        datasets: [{
            data: [12, 19, 23, 15, 32],
            backgroundColor: [
                'rgba(255, 99, 132, 0.5)',
                'rgba(255, 159, 64, 0.5)',
                'rgba(255, 206, 86, 0.5)',
                'rgba(75, 192, 192, 0.5)',
                'rgba(54, 162, 235, 0.5)',
            ],
            label: 'Dataset 1',
        }],
        labels: [
            'Rojo',
            'Naranja',
            'Amarillo',
            'Verde',
            'Azul'
        ]
    },
    options: {
        responsive: true,
        legend: {
            position: 'right',
        },
        title: {
            display: true,
            text: 'Gráfica Polar'
        },
        scale: {
            ticks: {
                beginAtZero: true
            },
            reverse: false
        },
        animation: {
            animateRotate: false,
            animateScale: true
        }
    }
}\chart


Radar

\chart(id: 'chartRadar1', width: '70%', height: '60%') {
    type: 'radar',
    data: {
        labels: [
            'Ene','Feb','Mar','Abr','May','Jun','Jul'
        ],
        datasets: [
            {
                label: 'Muestra 1',
                data: [65,59,90,81,56,55,40],
                backgroundColor: 'rgba(255, 99, 132, 0.2)',
                borderColor: 'rgba(255,99,132, 0.8)',
                pointBackgroundColor: 'rgba(255,99,132,1)',
                pointBorderColor: '#fff',
                pointHoverBorderColor: 'rgba(255,99,132,1)',
                fill: true
            }, {
                label: 'Muestra 2',
                data: [28,48,40,19,96,27,100],
                backgroundColor: 'rgba(54, 162, 235, 0.2)',
                borderColor: 'rgba(54, 162, 235, 0.8)',
                pointBackgroundColor: 'rgba(54, 162, 235,1)',
                pointBorderColor: '#fff',
                pointHoverBorderColor: 'rgba(54, 162, 235,1)',
                fill: true
            }
        ],
        pointStyle: 'crossRot',
    },
    options: {
        responsive: true,
        maintainAspectRatio: true,
        spanGaps: false,
        elements: {
            line: {
                tension: 0,
                borderWidth: 3
            }
        },
        plugins: {
            filler: {
                propagate: false
            },
            'samples-filler-analyser': {
                target: 'chart-div-chartRadar1'
            }
        }
    }
}\chart

Combinados

\chart(id: 'chartCombo1', width: '100%', height: '100%') {
    type: 'bar',
    data: {
        labels: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio', 'Julio'],
        datasets: [{
            type: 'line',
            label: 'Muestra 1',
            borderColor: 'rgba(54, 162, 235, 1)',
            borderWidth: 2,
            fill: false,
            data: [8, -19, 3, 12, -2, 11, -8]
        }, {
            type: 'bar',
            label: 'Muestra 2',
            backgroundColor: 'rgba(255,99,132,1)',
            borderColor: 'white',
            borderWidth: 2,
            data: [4, 9, 12, 2, 5, 6, 17],
        }, {
            type: 'bar',
            label: 'Muestra 3',
            backgroundColor: 'rgba(75, 192, 192, 1)',
            data: [-14, -5, 8, 12, -3, 9, -4],
        }]
    },
    options: {
        responsive: true,
        title: {
            display: true,
            text: 'Gráfica Combinada'
        },
        tooltips: {
            mode: 'index',
            intersect: true
        },
    }
}\chart

Diagramas

El Dokumentador introduce el manejo de diagramas basados en Blockdiag .

Flujo

Soporte a Diagramas de Flujo  

Temporal Image

blockdiag In 1 B E D F 6 6 G 6 Send …

blockdiag {
    A [shape = "flowchart.database", numbered = 1, label = "In"];
    B [shape = "cloud"];
    C [label="", style = dotted];
    D [shape = "actor"];
    E [shape = "diamond", color = cyan];
    F [shape = "note", textcolor=blue, fontsize=20];
    G [shape = "mail", numbered = 6,  stacked];
    C -> D [color = "red"];
    F -> G [folded, label='Send mail'];
    A -> B -> C <-> D;
    A -> E -> F -> G;
}

Secuencia

Soporte a Diagramas de Secuencia  

Temporal Image

blockdiag browser webserver database Apache works! GET /index.html POST /blog/comment INSERT comment

seqdiag {
    browser  -> webserver [label = "GET /index.html"];
    browser <-- webserver;
    browser  -> webserver [label = "POST /blog/comment"];
                webserver  -> database [label = "INSERT comment"];
                webserver <-- database;
    browser <-- webserver [note = "Apache works!"];
}

Actividades  

Soporte a Diagramas de Actividades  

Temporal Image

blockdiag User actdiag Writing REST Convert REST to Image Get diagram IMAGE

actdiag {
    write -> convert -> image
    lane user {
        label = "User"
        write [label = "Writing REST"];
        image [label = "Get diagram IMAGE"];
    }
    lane actdiag {
        convert [label = "Convert REST to Image"];
    }
}

Gantt

El soporte a los diagramas de Gantt están basados en el proyecto Frappe Gant  

Diagrama 1

Temporal Image

Diagrama 2

Temporal Image

Diagrama 1

\gantt(id: 'gantt1', view_mode: 'Day', date_format: 'YYYY-MM-DD', viewmode_ctrl: false) {
    {
        id: 'Task 1',
        name: 'Preparar documentación',
        start: '2018-06-28',
        end: '2018-06-30',
        progress: 50,
    }, {
        id: 'Task 2',
        name: 'Generar documentación',
        start: '2018-07-01',
        end: '2018-07-05',
        progress: 10,
        dependencies: 'Task 1'
    }, {
        id: 'Task 3',
        name: 'Entrega de documentación',
        start: '2018-07-06',
        end: '2018-07-06',
        progress: 0,
        dependencies: 'Task 1, Task 2'
    }, {
        id: 'Task 4',
        name: 'Revisión de documentación',
        start: '2018-07-07',
        end: '2018-07-07',
        progress: 0,
        dependencies: 'Task 3'
    }
}\gantt


Diagrama 2

\gantt(id: 'gantt2', view_mode: 'Week', date_format: 'YYYY-MM-DD', viewmode_ctrl: true, height: '280px') {
    {
        id: 'Task 1',
        name: 'Análisis de Requerimientos',
        start: '2018-08-01',
        end: '2018-08-03',
        progress: 100,
        custom_class: 'cc-green',
    }, {
        id: 'Task 2',
        name: 'Recepción de documentación',
        start: '2018-08-02',
        end: '2018-08-03',
        progress: 95,
        dependencies: 'Task 1'
    }, {
        id: 'Task 3',
        name: 'Análisis de Proyecto',
        start: '2018-08-04',
        end: '2018-08-10',
        progress: 55,
        dependencies: 'Task 1, Task 2'
    }, {
        id: 'Task 4',
        name: 'Desarrollo de Aplicativo',
        start: '2018-08-11',
        end: '2018-08-21',
        progress: 10,
        dependencies: 'Task 3'
    }, {
        id: 'Task 5',
        name: 'Fin de desarrollo',
        start: '2018-08-22',
        end: '2018-08-22',
        progress: 0,
        dependencies: 'Task 4',
        custom_class: 'cc-red',
    }
}\gantt

Utilerías Markdown  

Extractores  

El Documentador cuenta con un plugin para extraer la documentación embebida de archivos fuentes para los siguientes lenguajes de programación:

Convertidores  

Para facilitar la conversión de archivos entre distintos tipos, la comunidad creo Pandoc, esta herramienta es multiplataforma y nos permite convertir nuestros documentos actuales de otros formatos a Markdown, algunos ejemplos del sitio de demos de otros formatos a Markdown son:

  1. De página Web (HTML)

    pandoc -s -f html -t markdown_mmd https://es.wikipedia.org/wiki/Markdown -o WikiExample.md

  2. Docx

    pandoc -s -f docx -t markdown_mmd example29.docx -o DocxExample.md

  3. Epub

    pandoc -s -f epub -t markdown_mmd MANUAL.epub -o EpubExample.md

  4. DocBook

    pandoc -s -f docbook -t markdown_mmd howto.xml -o DocbookExample.md

Para mayor información sobre su uso se puede consultar el manual en linea de Pandoc.

Editores de Texto  

Se recomiendan los siguientes editores de texto con soporte Markdown:

Adicionalmente es necesario instalar el plugin para edición con Markdown MarkdonEditing

Remarkable Editor

Remarkable Editor

Instalación para Linux OpenSuse 15.X & 42.X:

$ zypper in python3-Markdown libwebkit2gtk libwebkit2gtk3 webkit2gtk3-devel typelib-1_0-GtkSource-3_0
$ zypper in libwkhtmltox0 python3-beautifulsoup4 wkhtmltopdf
$ zypper in remarkable-1.87-1.rpm

Nota: Ignorar dependencias, aun falla

  • Kate   Windows / Linux

Kate Editor

Instalación para Linux OpenSuse 15.X & 42.X:

$ zypper in kate
  • Atom   Windows / Linux

Atom Editor

Instalación para Linux OpenSuse 15.X & 42.X:

$ zypper in atom.x86_64.rpm

MarkdownPad Editor

Notas

Desarrollo de Manuales  

Se recomienda que para agregar nuevos manuales, se cree una carpeta por tópico dentro de la carpeta docs/extras, esta documentación se creó sobre la carpeta docs/extras/dokum

docs                # Carpeta que contiene las definiciones de la documentación
docs/extras         # Carpeta para documentación por módulos
docs/extras/dokum   # Documentación del módulo de Dokumentador

Nota: Los proyectos con un sistema de control de versiones como Git o SVN, deben excluir la carpeta de construcción de la documentación target\site.