Diretrizes do Guia Ruby on Rails

1 Markdown

Os guias são escritos em GitHub Flavored Markdown. Há uma documentação abrangente para Markdown, bem como uma folha de referência.

Cada guia deve começar com um texto motivacional no topo (essa é a pequena introdução na área azul). O prólogo deve dizer ao leitor sobre o que é o guia e o que eles aprenderão. Como exemplo, veja o Guia de Roteamento.

3 Títulos

O título de cada guia usa um cabeçalho h1; as seções do guia usam cabeçalhos h2; as subseções usam cabeçalhos h3; etc. Observe que a saída HTML gerada usará tags de cabeçalho começando com <h2>.

Título do Guia
===========

Seção
-------

### Subseção

Ao escrever títulos, capitalize todas as palavras, exceto preposições, conjunções, artigos internos e formas do verbo "ser":

#### Afirmações e Testes de Trabalhos dentro de Componentes
#### Pilha de Middleware é um Array
#### Quando os Objetos são Salvos?

Use a mesma formatação inline que o texto regular:

##### A Opção `:content_type`

4 Link para a API

Os links para a API (api.rubyonrails.org) são processados pelo gerador de guias da seguinte maneira:

Links que incluem uma tag de versão são deixados intactos. Por exemplo

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

não é modificado.

Por favor, use esses links nas notas de lançamento, pois eles devem apontar para a versão correspondente, independentemente do destino gerado.

Se o link não incluir uma tag de versão e os guias de desenvolvimento estiverem sendo gerados, o domínio é substituído 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 incluir uma tag de versão e os guias de lançamento estiverem sendo gerados, a versão do Rails é injetada. Por exemplo, se estivermos gerando os guias 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 faça links para edgeapi.rubyonrails.org manualmente.

5 Diretrizes de Documentação da API

Os guias e a API devem ser coerentes e consistentes quando apropriado. Em particular, estas seções das Diretrizes de Documentação da API também se aplicam aos guias:

6 Guias HTML

Antes de gerar os guias, certifique-se de ter a versão mais recente do Bundler instalada em seu sistema. Para instalar a versão mais recente do Bundler, execute gem install bundler.

Se você já tiver o Bundler instalado, você pode atualizá-lo com gem update bundler.

6.1 Geração

Para gerar todos os guias, basta entrar no diretório guides, executar bundle install e executar:

$ bundle exec rake guides:generate

$ bundle exec rake guides:generate:html

Os arquivos HTML resultantes podem ser encontrados no diretório ./output.

Para processar my_guide.md e nada mais, use a variável de ambiente ONLY:

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

Por padrão, os guias que não foram modificados não são processados, então ONLY raramente é necessário na prática.

Para forçar o processamento de todos os guias, passe ALL=1.

Se você quiser gerar guias em um idioma diferente do inglês, você pode mantê-los em um diretório separado em source (por exemplo, source/es) e usar a variável de ambiente GUIDES_LANGUAGE:

$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

Se você quiser ver todas as variáveis de ambiente que pode usar para configurar o script de geração, execute:

$ rake

6.2 Validação

Por favor, valide o HTML gerado com:

$ bundle exec rake guides:validate

Em particular, os títulos recebem um ID gerado a partir de seu conteúdo e isso muitas vezes leva a duplicatas.

7 Guias Kindle

7.1 Geração

Para gerar guias para o Kindle, use a seguinte tarefa rake:

$ bundle exec rake guides:generate:kindle

Feedback

Você é incentivado a ajudar a melhorar a qualidade deste guia.

Por favor, contribua se encontrar algum erro de digitação ou factual. Para começar, você pode ler nossa contribuição à documentação seção.

Você também pode encontrar conteúdo incompleto ou desatualizado. Por favor, adicione qualquer documentação ausente para o principal. Certifique-se de verificar Guias Edge primeiro para verificar se os problemas já foram corrigidos ou não no branch principal. Verifique as Diretrizes dos Guias do Ruby on Rails para estilo e convenções.

Se por algum motivo você encontrar algo para corrigir, mas não puder corrigi-lo você mesmo, por favor abra uma issue.

E por último, mas não menos importante, qualquer tipo de discussão sobre a documentação do Ruby on Rails é muito bem-vinda no Fórum oficial do Ruby on Rails.

Chapters