1. Sistemas de documentación¶

Dos partes: Sistemas de documentación web y de indexación

1.1 Gestion Documentos web¶

Algunos de los paquetes disponibeles:
- Sphinx and ReadTheDocs y - web
- https://matplotlib.org/sampledoc/

1.1.1 MKDOCS¶

Simple y directo para creación de páginas estáticas [Mkdocs web])https://www.mkdocs.org/)

Módulos en python. Guia de inicio
En este servidor instalado en el entorno ./Proy/mienv, que debe activarse...

pip install mkdocs

pip install mkdocs-material

pip install mkdocs-mermaid2-plugin[test]

pip install mkdocs-monorepo-plugin

pip3 install mkdocs-enumerate-headings-plugin

1.1.1.1 Commands¶

For full documentation visit mkdocs.org. * mkdocs new [dir-name] - Create a new project. * mkdocs serve - Start the live-reloading docs server. * mkdocs build - Build the documentation site. * mkdocs -h - Print help message and exit.

1.1.1.2 Project layout¶

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

1.1.1.3 Code Blocks (ver doc)¶

La colorización de la sintásis de los bloques de código se realiza en el desarrollo con Pygments y en tiempo ejecución con Javascript

Configuración
en mkdocs.yml:

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

Enlaces

titulo

Añadimos la siguiente línea en la cabecera del bloque
py title="bubble_sort.py"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Número de líneas py linenums="1"

Subrayado de lineas

py hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Bloques código inline

Es necesario activar la extensión de markdown inlineHilite.

Se activa en mkdocs.yml

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite

Ejemplo:

The `#!python range()` function is used to generate a sequence of numbers.

Incluir ficheros Con la extensión de markdown snippet configurada se pueden incluir ficheros de cualquier tipo.
Se configuran con

markdown_extensions:
  - pymdownx.snippets

   ``` title=".browserslistrc"
    --8<--​ ".browserslistrc"
    ```

--8<--​".browserslistrc"

1.1.1.4 Plugin¶

Existen dos tipos de plugin: incluidos con mkdocs y de terceros.
Como ejemplo de los plugin incluidos, tenemos search.
Para la lista de plugins:

• La oficial
• Paquete con multiples plugin
• Artículo sobre los mejores plugin

1.1.1.4.1 search¶

Tenemos la lista de plugin en github, y una amplio artículo sobre plugin disponibles y mas

Cuando se incluyen otros plugin, se deben configurar los incluidos:

plugins:
    search: {}
    your_other_plugin:
        option1: value
        option2: other value

1.1.1.4.2 mkpdf¶

Genera documentación en formato pdf (en git)

plugins:
    - search
    - mkpdfs

Para Ubuntu, instalar primero:

apt install python3-pip python3-cffi python3-brotli libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0

python3 --version
pango-view --version
If the version of Pango provided by your distribution is too old, you can use version 52.5 of WeasyPrint which does not need recent Pango features.

pip install weasyprint
weasyprint --info

1.1.1.4.3 Material for mkdocs¶

El mejor plugin de tema : material for mkdocs
Enlace a ref de material Algunas configuraciones usadas: Navigation tabs. Muestra barra de navegación en la cabecera con pantallas grandes.

theme:
  features:
    - navigation.tabs

 .md-grid {
  max-width: initial; 
}

1.1.1.4.4 mkdocs-mermaid2-plugin¶

Permite incluir ficheros mermaid en ficheros markdown.
Repositorio en github.
Instalación:

pip install mkdocs-mermaid2-plugin

plugins:
    - search
    - mermaid2

graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]

Para usar los gráficos mermaid:

• Instrucciones para diseñar un diagrama, ver the official website.
• Si necesitas una introducción:.
• Para probar online los diagramas Mermaid Live Editor.

1.1.1.4.5 monorepo¶

Plugin para integrar varios proyecto mkdocs en uno.
Para instalar monorepo:

$ pip install mkdocs-monorepo-plugin

1.1.1.4.6 mkdocstring¶

Documentación automática desde el código fuente para mkdocs (mkdocstring)

1.1.1.5 Como integrar ficheros html¶

El objetivo sería mantener el menú lateral.

1.2 Sistemas de indexación¶

Tenemos:

Xapian

1.3 Lenguaje MARKDOWN¶

Para empezar esta guía opensource que incluye una hoja resumen

En especial, para incluir html seguimos estos consejos

Javascript se pasa tal y como se escribe en el .md.
Si se necesitan librerias se incluyen en el fichero de configuración

1.3.1 Trucos¶

Para incluir imagenes de Google Drive : Obtenemos la dirección, por ejemplo: https://drive.google.com/file/d/1cMaJWkL_KBACvlXwBqIlCRm1qyYIqeON/view y utilizamos la siguiente notación:

![caja](https://drive.google.com/uc?export=view&id=1cMaJWkL_KBACvlXwBqIlCRm1qyYIqeON) 
Es decir :  
https://drive.google.com/uc?export=view&id=[id_imagen]  id_imagen obtenido del enlace de drive

1.4 Herramientas para enseñar javascript y otros¶

Un punto de inicio interesante es el proyecto de google Open Online Education y su course builder
Para un manual en español de la uam

Sigue en este documento local

1.5 Otras Herramientas¶

• Herramientas video, audio blackboard: artículo

1.5.1 Editor en javascript codemirror¶

Codemirror es un editor de texto implementado en javascript y con soporte para varios lenguajes de programación

1.5.2 Playground opensource integrables en paginas¶

1.5.2.1 Runjs¶

runjs es un playground para desktop.

1.5.2.2 Flems¶

Flems es una app web estátics permite .... Como editor utiliza codemirror. Para usarlo se utiliza el siguiente código:

<script src="https://flems.io/flems.html" type="text/javascript" charset="utf-8"></script>
<script>
const flems = Flems(document.body, {
    files: [{
        name: 'app.js',
        content: 'm.render(document.body, m("h1", "Hello world"))'
    }],
    links: [{
        name: 'mithril',
        type: 'script',
        url: 'https://unpkg.com/mithril'
    }]
})
</script>

1.5.3 OTROS A EXPLORAR¶

• Javascript sanbox
• Editr

1.5.3.1 Richie¶

Richie es un CMS para cursos basado en Django y distribuido usando docker.

1.6 Prueba con botones javascript¶

Pulsa