Guías de Ruby on Rails - Directrices

1 Markdown

Las guías se escriben en Markdown con formato GitHub. Existe una documentación completa para Markdown, así como una hoja de referencia.

Cada guía debe comenzar con un texto motivador en la parte superior (esa es la pequeña introducción en el área azul). El prólogo debe decirle al lector de qué trata la guía y qué aprenderá. Como ejemplo, consulta la Guía de enrutamiento.

3 Encabezados

El título de cada guía utiliza un encabezado h1; las secciones de la guía utilizan encabezados h2; las subsecciones utilizan encabezados h3; etc. Ten en cuenta que la salida HTML generada utilizará etiquetas de encabezado que comienzan con <h2>.

Título de la Guía
=================

Sección
-------

### Subsección

Al escribir encabezados, se deben capitalizar todas las palabras excepto las preposiciones, conjunciones, artículos internos y formas del verbo "ser":

#### Afirmaciones y pruebas de trabajos dentro de componentes
#### La pila de middleware es un arreglo
#### ¿Cuándo se guardan los objetos?

Utiliza el mismo formato en línea que el texto regular:

##### La opción `:content_type`

4 Enlaces a la API

Los enlaces a la API (api.rubyonrails.org) son procesados por el generador de guías de la siguiente manera:

Los enlaces que incluyen una etiqueta de versión se dejan sin cambios. Por ejemplo:

https://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html

no se modifica.

Utiliza estos enlaces en las notas de la versión, ya que deben apuntar a la versión correspondiente sin importar el destino que se esté generando.

Si el enlace no incluye una etiqueta de versión y se están generando guías de desarrollo, el dominio se reemplaza por edgeapi.rubyonrails.org. Por ejemplo:

https://api.rubyonrails.org/classes/ActionDispatch/Response.html

se convierte en

https://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html

Si el enlace no incluye una etiqueta de versión y se están generando guías de una versión específica, se inyecta la versión de Rails. Por ejemplo, si estamos generando las guías para v5.1.0, el enlace

https://api.rubyonrails.org/classes/ActionDispatch/Response.html

se convierte en

https://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html

Por favor, no enlaces a edgeapi.rubyonrails.org manualmente.

5 Directrices de Documentación de la API

Las guías y la API deben ser coherentes y consistentes cuando corresponda. En particular, estas secciones de las Directrices de Documentación de la API también se aplican a las guías:

6 Guías en HTML

Antes de generar las guías, asegúrate de tener la última versión de Bundler instalada en tu sistema. Para instalar la última versión de Bundler, ejecuta gem install bundler.

Si ya tienes Bundler instalado, puedes actualizarlo con gem update bundler.

6.1 Generación

Para generar todas las guías, simplemente ve al directorio guides, ejecuta bundle install y luego ejecuta:

$ bundle exec rake guides:generate

$ bundle exec rake guides:generate:html

Los archivos HTML resultantes se pueden encontrar en el directorio ./output.

Para procesar solo my_guide.md y nada más, utiliza la variable de entorno ONLY:

$ touch my_guide.md
$ bundle exec rake guides:generate ONLY=my_guide

De forma predeterminada, las guías que no se han modificado no se procesan, por lo que ONLY rara vez es necesario en la práctica.

Para forzar el procesamiento de todas las guías, pasa ALL=1.

Si deseas generar guías en un idioma distinto al inglés, puedes mantenerlas en un directorio separado dentro de source (por ejemplo, source/es) y utilizar la variable de entorno GUIDES_LANGUAGE:

$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

Si deseas ver todas las variables de entorno que puedes utilizar para configurar el script de generación, simplemente ejecuta:

$ rake

6.2 Validación

Por favor, valida el HTML generado con:

$ bundle exec rake guides:validate

En particular, los títulos obtienen un ID generado a partir de su contenido y esto a menudo genera duplicados.

7 Guías para Kindle

7.1 Generación

Para generar guías para Kindle, utiliza la siguiente tarea de rake:

$ bundle exec rake guides:generate:kindle

Comentarios

Se te anima a ayudar a mejorar la calidad de esta guía.

Por favor, contribuye si encuentras algún error tipográfico o factual. Para empezar, puedes leer nuestra contribución a la documentación sección.

También puedes encontrar contenido incompleto o desactualizado. Por favor, añade cualquier documentación faltante para main. Asegúrate de revisar Edge Guides primero para verificar si los problemas ya están resueltos o no en la rama principal. Consulta las Directrices de las Guías de Ruby on Rails para el estilo y las convenciones.

Si por alguna razón encuentras algo que corregir pero no puedes solucionarlo tú mismo, por favor abre un problema.

Y por último, cualquier tipo de discusión sobre la documentación de Ruby on Rails es muy bienvenida en el Foro oficial de Ruby on Rails.