Ruby on Rails Gidų gairės

1 Markdown

Gidai rašomi naudojant GitHub Flavored Markdown. Yra išsamios Markdown dokumentacijos, taip pat cheatsheet.

Kiekvienas gidui turėtų prasidėti motyvuojančiu tekstu viršuje (tai mažas įvado tekstas mėlynajame lauke). Prologas turėtų pasakyti skaitytojui, apie ką yra gidai ir ką jie sužinos. Pavyzdžiui, žr. Maršrutizavimo gidą.

3 Antraštės

Kiekvieno gido pavadinimas naudoja h1 antraštę; gido skyriai naudoja h2 antraštes; posekiai naudoja h3 antraštes; ir t.t. Atkreipkite dėmesį, kad sugeneruotas HTML išvestis naudos antraščių žymas pradedant nuo <h2>.

Gido pavadinimas
===========

Skyrius
-------

### Po-skyrius

Rašant antraštes, didžiosios raides naudojamos visiems žodžiams, išskyrus prielinksnius, jungtukus, vidinius straipsnius ir būdvardžio "būti" formas:

#### Teiginiai ir testavimo darbai komponentuose
#### Tarpinės eilutė yra masyvas
#### Kada objektai yra išsaugomi?

Naudokite tą patį įterpimo formatavimą kaip ir įprastam tekste:

##### `:content_type` parinktis

4 Nuorodos į API

Nuorodos į API (api.rubyonrails.org) yra apdorojamos gidų generatoriumi pagal šią tvarką:

Nuorodos, kuriose yra išleidimo žyma, lieka nepakeistos. Pavyzdžiui

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

nekeičiama.

Prašome naudoti šias nuorodas išleidimo pastabose, nes jos turėtų rodyti į atitinkamą versiją, nepriklausomai nuo generuojamo tikslo.

Jei nuoroda neįtraukia išleidimo žymos ir generuojami kairės gidai, domenas pakeičiamas į edgeapi.rubyonrails.org. Pavyzdžiui,

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

tampa

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

Jei nuoroda neįtraukia išleidimo žymos ir generuojami išleidimo gidai, įterpiamas Rails versija. Pavyzdžiui, jei generuojame gidus v5.1.0 versijai, nuoroda

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

tampa

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

Prašome rankiniu būdu neįtraukti nuorodų į edgeapi.rubyonrails.org.

5 API dokumentacijos gairės

Gidai ir API turėtų būti suderinti ir nuoseklūs, kai tai yra tinkama. Ypač šie API dokumentacijos gairių skyriai taip pat taikomi gidams:

6 HTML gidai

Prieš generuojant gidus, įsitikinkite, kad jūsų sistemoje įdiegta naujausia Bundler versija. Norėdami įdiegti naujausią Bundler versiją, paleiskite gem install bundler.

Jei jau turite įdiegtą Bundler, galite atnaujinti naudodami gem update bundler.

6.1 Generavimas

Norėdami sugeneruoti visus gidus, tiesiog pereikite į guides katalogą, paleiskite bundle install ir vykdykite:

$ bundle exec rake guides:generate

arba

$ bundle exec rake guides:generate:html

Rezultatų HTML failai rasomi ./output kataloge.

Norėdami apdoroti tik my_guide.md ir nieko kito, naudokite ONLY aplinkos kintamąjį:

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

Pagal numatytuosius nustatymus gidai, kurie nebuvo modifikuoti, neapdorojami, todėl ONLY praktiškai retai reikalingas.

Norėdami priversti apdoroti visus gidus, perduokite ALL=1.

Jei norite generuoti gidus kitomis nei anglų kalba, galite juos laikyti atskirame kataloge po source (pvz., source/es) ir naudoti GUIDES_LANGUAGE aplinkos kintamąjį:

$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

Jei norite pamatyti visus aplinkos kintamuosius, kuriuos galite naudoti konfigūruoti generavimo scenarijų, tiesiog paleiskite:

$ rake

6.2 Validacija

Prašome patikrinti sugeneruotą HTML naudojant:

$ bundle exec rake guides:validate

Ypač, pavadinimai gauna ID, kuris yra sugeneruojamas iš jų turinio, ir tai dažnai sukelia dublikatus.

7 Kindle gidai

7.1 Generavimas

Norėdami generuoti gidus Kindle, naudokite šią rake užduotį:

$ bundle exec rake guides:generate:kindle

Atsiliepimai

Jūs esate skatinami padėti pagerinti šio vadovo kokybę.

Prašome prisidėti, jei pastebite rašybos klaidų ar faktinių klaidų. Norėdami pradėti, galite perskaityti mūsų dokumentacijos prisidėjimo skyrių.

Taip pat gali būti nepilnos informacijos arba informacijos, kuri nėra atnaujinta. Prašome pridėti bet kokią trūkstamą dokumentaciją pagrindiniam. Patikrinkite Edge vadovus pirmiausia, ar problemas jau išspręsta arba ne pagrindinėje šakoje. Patikrinkite Ruby on Rails vadovų gaires dėl stiliaus ir konvencijų.

Jei dėl kokios nors priežasties pastebite kažką, ką reikia ištaisyti, bet negalite patys tai pataisyti, prašome pranešti apie problemą.

Ir galiausiai, bet ne mažiau svarbu, bet koks diskusijos dėl Ruby on Rails dokumentacijos yra labai laukiamos oficialiame Ruby on Rails forume.

Chapters