Chapters1 Markdown
Guias são escritos em GitHub Markdown. Para uma melhor compreensão existe a documentação para Markdown, assim como essas dicas.
2 Prólogo
Cada guia deve começar com um texto motivacional no topo (é uma pequena introdução na área azul). O prólogo deve dizer ao leitor qual será assunto do guia e o que o leitor vai aprender. Como exemplo, veja o Guia de Rotas.
3 Títulos
O título de cada guia usa um cabeçalho h1, seções de guia usam cabeçalho h2; subseções usam cabeçalho h3; etc. Note que o resultado gerado do HTML vai usar tags de cabeçalho começando com <h2>.
Título do Guia
===========
Sessão
-------
### Sub Sessão
Quando escrever cabeçalhos, capitalizar todas as palavras exceto para preposições, conjunções, artigos e formulários do verbo "ser":
#### Asserções e Testando *Jobs* dentro dos Componentes
#### *Middleware Stack* é um *Array*
#### Quando os Objetos são salvos?
Use a mesma formatação em linha como texto regular:
##### A `:content_type` Opção
4 Linkando com a API
Links para a API (api.rubyonrails.org) são processados por um gerador de guia a seguir:
Links que incluem a tag de lançamento não são tocadas, Por exemplo
https://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html
não é modificada.
Por favor use essas notas de lançamento, porque elas devem apontar para a versão correspondente, não importanto o alvo sendo gerado.
Se o link não incluir a tag de lançamento e os edge guias estiverem sendo gerados, o dominio é substituido por edgeapi.rubyonrails.org. Por exemplo,
https://api.rubyonrails.org/classes/ActionDispatch/Response.html
se torna
https://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html
Se o link não inclui a tag de lançamento e os guias de lançamento estiverem sendo gerados, a versão do Rails é aplicada, Por exemplo, se nós estamos gerando o guia para v5.1.0 o link
https://api.rubyonrails.org/classes/ActionDispatch/Response.html
se torna
https://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html
Por favor não linkar para edgeapi.rubyonrails.org manualmente.
5 API Documentation Guidelines
The guides and the API should be coherent and consistent where appropriate. In particular, these sections of the API Documentation Guidelines also apply to the guides:
6 HTML Guides
Before generating the guides, make sure that you have the latest version of Bundler installed on your system. You can find the latest Bundler version here. As of this writing, it's v1.17.1.
To install the latest version of Bundler, run gem install bundler.
6.1 Generation
To generate all the guides, just cd into the guides directory, run bundle install, and execute:
$ bundle exec rake guides:generate
or
$ bundle exec rake guides:generate:html
Resulting HTML files can be found in the ./output directory.
To process my_guide.md and nothing else use the ONLY environment variable:
$ touch my_guide.md
$ bundle exec rake guides:generate ONLY=my_guide
By default, guides that have not been modified are not processed, so ONLY is rarely needed in practice.
To force processing all the guides, pass ALL=1.
If you want to generate guides in a language other than English, you can keep them in a separate directory under source (e.g. source/es) and use the GUIDES_LANGUAGE environment variable:
$ bundle exec rake guides:generate GUIDES_LANGUAGE=es
If you want to see all the environment variables you can use to configure the generation script just run:
$ rake
6.2 Validation
Please validate the generated HTML with:
$ bundle exec rake guides:validate
Particularly, titles get an ID generated from their content and this often leads to duplicates.
7 Kindle Guides
7.1 Generation
To generate guides for the Kindle, use the following rake task:
$ bundle exec rake guides:generate:kindle
Feedback
Você é incentivado a ajudar a melhorar a qualidade deste guia.
Por favor, contribua caso veja quaisquer erros, inclusive erros de digitação. Para começar, você pode ler nossa sessão de contribuindo com a documentação.
Você também pode encontrar conteúdo incompleto ou coisas que não estão atualizadas. Por favor, adicione qualquer documentação em falta na main do Rails. Certifique-se de checar o Edge Guides (en-US) primeiro para verificar se o problema já foi resolvido ou não no branch main. Verifique as Diretrizes do Guia Ruby on Rails para estilo e convenções.
Se, por qualquer motivo, você encontrar algo para consertar, mas não conseguir consertá-lo, por favor abra uma issue no nosso Guia.
E por último, mas não menos importante, qualquer tipo de discussão sobre a documentação do Ruby on Rails é muito bem vinda na forum oficial do Ruby on Rails e nas issues do Guia em português.