Introducción a MkDocs

Introducción a MkDocs

  8:02:00 p.m.    ReggieClassic

---

MkDocs es un generador de sitios estáticos de software libre,  orientado a la documentación de proyectos. Se puede utilizar para generar un sitio independiente, o simplemente una sección de documentación de un sitio más grande.


Debido a que MkDocs produce archivos estáticos, la documentación es ligera y fácil de usar en servicios de hosting gratuitos como paginas de GitHub, Read the Docs y , por supuesto, en su propio servidor.

En este artículo, de introducción a  MkDocs, mostraremos cómo instalarlo, crear documentación con él y, finalmente, hospedar  la documentación que se genere en un servidor web.

Con el fin de instalar MkDocs se necesitará de Python instalado en el sistema, así como el gestor de paquetes de Python, pip. Puede comprobar si  estos ya se han instalado de esta manera:

$ python --version
Python 2.7.2

$ pip --version
pip 1.5.2

MkDocs soporta Python 2.6, 2.7, 3.3, 3.4 y 3.5.

Instale el paquete mkdocs usando pip:

pip install mkdocs

Ahora debería tener los commandos mkdocs instalados en el sistema. Ejecute mkdocs --version para comprobar que todo funciona bien.

$ mkdocs --version
mkdocs, version 0.15.2

Construyendo la Documentacion

Ahora que tiene Python y MkDocs configurados, puede seguir adelante con su documentación real.

En primer lugar, crearemos  un proyecto para la documentación (vamos a llamarlo sp-doc) y navegaremos hasta  la carpeta creada:

$ mkdocs new sp-doc
$ cd sp-doc

La carpeta de proyecto generado contendrá una carpeta de documentos, donde serán almacenados los archivos de la documentación y el archivo de configuración  mkdocs.yml.

Esta es la estructura de directorios:

|-- docs              # MD doc pages
    |-- index.md
|-- mkdocs.yml        # config file

Añada la siguiente configuración para el archivo mkdocs.yml:

site_name: Sitio de la Documentacion
site_description: Descripcion de la documentacion
theme: readthedocs
pages:
- ['index.md', 'Index']

MkDocs viene con una serie de temas, tales como "MkDocs", "Read the Docs" y "Bootstrap". Digamos que usted tiene la intención de utilizar el tema predeterminado. En ese caso, basta con sustituir readthedocs con mkdocs en el código de arriba.

La página de configuración se utiliza para determinar el conjunto de páginas que deben ser construidos para la documentación y el menú de navegación.

Los archivos añadidos después de la linea  pages deben ser relativos a la carpeta de cada documento. Por ejemplo, si ha creado una nueva carpeta llamada config dentro del directorio docs y añadido un archivo setup.md en ella, así es cómo debe añadirlo a pages en el archivo de configuración mkdocs.yml:

site_name: Sitio de la Documentacion
site_description: Descripcion de la documentacion
theme: readthedocs
pages:
- ['index.md', 'Index']
- ['start.md', 'Iniciar']
- ['config/setup.md', 'Configuracion', 'Setup']
- ['config/debug.md', 'Configuracion', 'Debug']

Esto crea algunas nuevas páginas que aparecen automáticamente en nuestro menú de documentación. En primer lugar, hay una página start.md, con el título "Iniciar".

También hemos añadido una nueva sección al menú de documentación denominada "configuración", en las que hay un enlace al nuevo programa de instalación y páginas de depuración.

MkDocs incluye un servidor web incorporado, para que pueda ver la documentación de forma local a medida que trabaja en ella.

Para iniciar el servidor web, asegúrese de que está en el directorio donde reside el archivo de configuración mkdocs.yml, y ejecute el comando mkdocs serve.

Ingrese http://127.0.0.1:8000 en su navegador para ver la documentación:

Si está satisfecho con lo que ha creado,  ejecute  mkdocs build para generar los archivos estáticos de la documentación que se guardaran en un directorio denominado site.

Puede copiar los archivos estáticos y alojarlos en un servidor web de su elección para tener la documentación en vivo.