1 Markdown
Las guías se escriben en Markdown con sabor a GitHub. Hay una documentación exhaustiva para Markdown, así como una hoja de referencia.
2 Prólogo
Cada guía debe comenzar con un texto motivacional 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, vea la Guía de Enrutamiento.
3 Encabezados
El título de cada guía usa un encabezado h1; las secciones de la guía usan encabezados h2; las subsecciones usan encabezados h3; etc. Tenga en cuenta que el HTML generado usará etiquetas de encabezado comenzando con <h2>.
Título de la Guía
=================
Sección
-------
### Sub Sección
Al escribir encabezados, capitalice todas las palabras excepto preposiciones, conjunciones, artículos internos y formas del verbo "ser":
#### Aserciones y Pruebas de Trabajos dentro de Componentes
#### La Pila de Middleware es un Array
#### ¿Cuándo se Guardan los Objetos?
Use el mismo formato en línea que el texto regular:
##### La Opción `:content_type`
4 Enlace al API
Los enlaces al 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 intactos. Por ejemplo
https://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html
no se modifica.
Por favor, use estos en notas de versión, ya que deben apuntar a la versión correspondiente sin importar el objetivo que se esté generando.
Si el enlace no incluye una etiqueta de versión y se están generando guías de borde, 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 lanzamiento, 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 enlace manualmente a edgeapi.rubyonrails.org.
5 Ajuste de Columnas
No reformatee guías antiguas solo para ajustar columnas. Pero las nuevas secciones y guías deben ajustarse a 80 columnas.
6 Directrices de Documentación del API
Las guías y el API deben ser coherentes y consistentes cuando sea apropiado. En particular, estas secciones de las Directrices de Documentación del API también se aplican a las guías:
7 Guías en HTML
Antes de generar las guías, asegúrese de tener la última versión de
Bundler instalada en su sistema. Para instalar la última versión de Bundler, ejecute gem install bundler.
Si ya tiene Bundler instalado, puede actualizar con gem update bundler.
7.1 Generación
Para generar todas las guías, simplemente cd en el directorio guides, ejecute bundle install, y ejecute:
$ bundle exec rake guides:generate
o
$ bundle exec rake guides:generate:html
Los archivos HTML resultantes se pueden encontrar en el directorio ./output.
Para procesar my_guide.md y nada más, use la variable de entorno ONLY:
$ touch my_guide.md
$ bundle exec rake guides:generate ONLY=my_guide
Por defecto, las guías que no han sido modificadas no se procesan, por lo que ONLY rara vez es necesario en la práctica.
Para forzar el procesamiento de todas las guías, pase ALL=1.
Si desea generar guías en un idioma que no sea inglés, puede mantenerlas en un directorio separado bajo source (por ejemplo, source/es) y usar la variable de entorno GUIDES_LANGUAGE:
$ bundle exec rake guides:generate GUIDES_LANGUAGE=es
Si desea ver todas las variables de entorno que puede usar para configurar el script de generación, simplemente ejecute:
$ rake
7.2 Validación
Por favor, valide el HTML generado con:
$ bundle exec rake guides:validate
Particularmente, los títulos obtienen un ID generado a partir de su contenido y esto a menudo lleva a duplicados.
8 Guías para Kindle
8.1 Generación
Para generar guías para Kindle, use 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 ves algún error tipográfico o errores fácticos. Para comenzar, puedes leer nuestra sección de contribuciones a la documentación.
También puedes encontrar contenido incompleto o cosas que no están actualizadas. Por favor agrega cualquier documentación faltante para main. Asegúrate de revisar Guías Edge primero para verificar si los problemas ya están resueltos o no en la rama principal. Revisa las Guías de Ruby on Rails para estilo y convenciones.
Si por alguna razón detectas algo que corregir pero no puedes hacerlo tú mismo, por favor abre un issue.
Y por último, pero no menos importante, cualquier tipo de discusión sobre la documentación de Ruby on Rails es muy bienvenida en el Foro oficial de Ruby on Rails.