Saltar al contenido principal

Documentación de Electron

· 5 lectura mínima
jlord
jlord

Esta semana hemos proporcionado la documentación de Electron un lugar en electronjs.org. Puedes visitar /docs/latest para el último conjunto de documentos. También, mantendremos versiones antiguas de documentos, así que podrás visitar /docs/vX.XX.X para los documentos que se corresponden con la versión que estás usando.

Puedes visitar /docs para ver qué versiones están disponibles o /docs/all para ver la última versión de los documentos en una sola página (perfecto para búsquedas cmd + f).

Si le gustaría contribuir con el contenido de los documentos, puede hacerlo en el repositorio de Electron, desde donde los documentos son obtenidos. Los obtenemos para cada lanzamiento menor y los añadimos al repositorio del sitio Electron, el cual es realizado con Jekyll.

Si está interesado en aprender más sobre cómo obtenemos los documentos de un repositorio a otro sigue leyendo a continuación. En otro caso, ¡disfrute de los documentos!

Los bit técnicos​

Estamos preservando la documentación dentro del repositorio núcleo de Electron tal como está. Esto significa que electron/electron siempre tendrá la última versión de los documentos. Cuando se liberan las versiones nuevas de Electron, las duplicamos en el repositorio del sitio web de Electron electron/electronjs.org.

script/docs​

Para obtener los documentos ejecutamos un guion con un interfaz de línea de instrucción del script/docs v.X.XX.X con o sin la opción --latest (dependiendo de si la versión que ha importado es la última versión). Nuestro guion para obtener los documentos utiliza unos módulos de Node interesantes:

Las pruebas nos ayudan a conocer que todos los bit y las piezas se comporten como se esperaba.

Jekyll​

El sitio web Electron es un sitio Jekyll y hacemos uso de la función Collections para los documentos con una estructura como ésta:

electron.atom.io
└── _docs
    ├── latest
    ├── v0.27.0
    ├── v0.26.0
    ├── so on
    └── so forth

Texto preliminar​

Para que Jekyll renderice cada página necesita al menos un asunto frontal vacío. Vamos a hacer uso de la materia frontal en todas nuestras páginas, así que mientras estamos transmitiendo el directorio /docs comprobamos si un archivo es el archivo README.md (en cuyo caso recibe una configuración de materia frontal) o si es cualquier otro archivo con una extensión markdown (en cuyo caso recibe una materia frontal ligeramente diferente).

Cada página recibe este conjunto de variables de la materia principal:

---
version: v0.27.0
category: Tutorial
title: 'Inicio rápido'
source_url: 'https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md'
---

El README.md obtiene un permalink adicional por lo que tiene una URL que tiene una raíz común de index.html en lugar de una /readme/ incómoda.

permalink: /es_ES/docs/v0.27.0/index.html

Configuración y redirecciones​

En el archivo _config.yml del sitio se establece una variable latest_version cada vez que se utiliza el indicador --latest al recuperar documentos. También añadimos una lista de todas las versiones que han sido añadidas al sitio así como el enlace permanente que nos gustaría para toda la colección de documentos.

latest_version: v0.27.0
available_versions:
  - v0.27.0
colecciones:
  docs: { output: true, permalink: '/docs/:path/' }

El archivo latest.md en nuestra raíz del sitio está en blanco excepto para este suceso frontal el cual concede a los usuarios ver el índice (como README) de la versión más última de los documentos visitando esta URL, electron.atom.io/docs/latest, en vez de utilizar el número de la última versión específicamente (a través del cual puede hacer eso, también).

---
permalink: /docs/latest/
redirect_to: /docs/{{ site.data.releases[0].version }}
---

Diseños​

En la plantilla de diseño docs.html utilizamos condicionales para mostrar u ocultar información en el encabezado y migaja.

{% raw %} {% if page.category != 'ignore' %}
<h6 class="docs-breadcrumb">
  {{ page.version }} / {{ page.category }} {% if page.title != 'README' %} / {{
  page.title }} {% endif %}
</h6>
{% endif %} {% endraw %}

Para crear una página mostrando las versiones que están disponibles, tan solo hacemos un bucle a través de la lista en nuestra configuración de un archivo, versions.md, en la raíz del sitio. También proporcionamos a esta página un enlace permanente: /docs/

{% raw %} {% for version in site.available_versions %} - [{{ version
}}](/docs/{{ version }}) {% endfor %} {% endraw %}

¡Espero que hayas disfrutado de estos trazos técnicos! Si estás interesado en más información sobre el uso de Jekyll para sitios de documentación, revisa cómo el equipo de documentación pública de GitHub en los documentos de GitHub en Jekyll.