Directives de Ruby on Rails Guides

1 Markdown

Les guides sont rédigés en Markdown compatible avec GitHub. Il existe une documentation complète pour Markdown, ainsi qu'une feuille de triche.

Chaque guide devrait commencer par un texte de motivation en haut (c'est l'introduction dans la zone bleue). Le prologue devrait indiquer au lecteur de quoi parle le guide et ce qu'il apprendra. Par exemple, consultez le Guide de routage.

3 Titres

Le titre de chaque guide utilise un titre h1; les sections du guide utilisent des titres h2; les sous-sections utilisent des titres h3; etc. Notez que le code HTML généré utilisera des balises de titre commençant par <h2>.

Titre du guide
==============

Section
-------

### Sous-section

Lors de la rédaction des titres, mettez en majuscule tous les mots, sauf les prépositions, les conjonctions, les articles internes et les formes du verbe "être" :

#### Assertions et tests d'emplois à l'intérieur des composants
#### La pile de middleware est un tableau
#### Quand les objets sont-ils enregistrés ?

Utilisez le même formatage en ligne que pour le texte normal :

##### L'option `:content_type`

4 Lien vers l'API

Les liens vers l'API (api.rubyonrails.org) sont traités par le générateur de guides de la manière suivante :

Les liens qui incluent une balise de version sont laissés intacts. Par exemple :

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

n'est pas modifié.

Veuillez utiliser ces liens dans les notes de version, car ils doivent pointer vers la version correspondante, quelle que soit la cible générée.

Si le lien n'inclut pas de balise de version et que les guides de développement sont générés, le domaine est remplacé par edgeapi.rubyonrails.org. Par exemple :

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

devient

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

Si le lien n'inclut pas de balise de version et que les guides de version sont générés, la version de Rails est injectée. Par exemple, si nous générons les guides pour v5.1.0, le lien

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

devient

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

Veuillez ne pas créer de lien vers edgeapi.rubyonrails.org manuellement.

5 Directives de documentation de l'API

Les guides et l'API doivent être cohérents et cohérents lorsque cela est approprié. En particulier, ces sections des Directives de documentation de l'API s'appliquent également aux guides :

6 Guides HTML

Avant de générer les guides, assurez-vous d'avoir la dernière version de Bundler installée sur votre système. Pour installer la dernière version de Bundler, exécutez gem install bundler.

Si vous avez déjà Bundler installé, vous pouvez le mettre à jour avec gem update bundler.

6.1 Génération

Pour générer tous les guides, accédez simplement au répertoire guides, exécutez bundle install et exécutez :

$ bundle exec rake guides:generate

$ bundle exec rake guides:generate:html

Les fichiers HTML résultants se trouvent dans le répertoire ./output.

Pour traiter uniquement my_guide.md et rien d'autre, utilisez la variable d'environnement ONLY :

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

Par défaut, les guides qui n'ont pas été modifiés ne sont pas traités, donc ONLY est rarement nécessaire en pratique.

Pour forcer le traitement de tous les guides, passez ALL=1.

Si vous souhaitez générer des guides dans une autre langue que l'anglais, vous pouvez les conserver dans un répertoire séparé sous source (par exemple, source/es) et utiliser la variable d'environnement GUIDES_LANGUAGE :

$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

Si vous souhaitez voir toutes les variables d'environnement que vous pouvez utiliser pour configurer le script de génération, exécutez simplement :

$ rake

6.2 Validation

Veuillez valider le HTML généré avec :

$ bundle exec rake guides:validate

En particulier, les titres obtiennent un ID généré à partir de leur contenu et cela conduit souvent à des doublons.

7 Guides Kindle

7.1 Génération

Pour générer des guides pour le Kindle, utilisez la tâche rake suivante :

$ bundle exec rake guides:generate:kindle

Retour d'information

Vous êtes encouragé à contribuer à l'amélioration de la qualité de ce guide.

Veuillez contribuer si vous trouvez des fautes de frappe ou des erreurs factuelles. Pour commencer, vous pouvez lire notre contribution à la documentation section.

Vous pouvez également trouver du contenu incomplet ou des informations qui ne sont pas à jour. Veuillez ajouter toute documentation manquante pour la version principale. Assurez-vous de vérifier Edge Guides d'abord pour vérifier si les problèmes ont déjà été résolus ou non sur la branche principale. Consultez les Directives des guides Ruby on Rails pour le style et les conventions.

Si pour une raison quelconque vous repérez quelque chose à corriger mais ne pouvez pas le faire vous-même, veuillez ouvrir un problème.

Et enfin, toute discussion concernant la documentation de Ruby on Rails est la bienvenue sur le Forum officiel de Ruby on Rails.

Chapters