Nette Documentation Preview

syntax 
Como Contribuir para a Documentação
***********************************

.[perex]
Contribuir para a documentação é uma das atividades mais gratificantes, pois ajuda outros a entender o framework.


Como Escrever?
--------------

A documentação destina-se principalmente a pessoas que estão a familiarizar-se com o tópico. Portanto, deve cumprir vários pontos importantes:

- Comece pelo simples e geral. Avance para tópicos mais complexos apenas no final.
- Tente explicar o assunto da melhor forma possível. Por exemplo, tente explicar primeiro o tópico a um colega.
- Forneça apenas as informações que o utilizador realmente precisa saber sobre o tópico em questão.
- Verifique se as suas informações são realmente verdadeiras. Teste cada trecho de código.
- Seja conciso - reduza o que escreveu pela metade. E depois, se necessário, novamente.
- Use com moderação todos os tipos de destaque, desde negrito até caixas como `.[note]`.
- No código, siga os [Padrões de Codificação |coding-standard].

Aprenda também a [sintaxe |syntax]. Para pré-visualizar o artigo enquanto o escreve, pode usar o [editor com pré-visualização |https://editor.nette.org/].


Versões de Idioma
-----------------

O idioma principal é o inglês. As suas alterações devem ser, portanto, em inglês. Se o inglês não for o seu forte, use o [DeepL Translator |https://www.deepl.com/translator] e outros irão rever o seu texto.

A tradução para outros idiomas será feita automaticamente após a aprovação e ajuste da sua modificação.


Modificações Triviais
---------------------

Para contribuir para a documentação, é essencial ter uma conta no [GitHub|https://github.com].

A forma mais fácil de fazer uma pequena alteração na documentação é usar os links no final de cada página:

- *Mostrar no GitHub* abre a versão do código-fonte da página no GitHub. Depois, basta pressionar o botão `E` para começar a editar (é necessário estar autenticado no GitHub).
- *Abrir pré-visualização* abre o editor, onde pode ver imediatamente a aparência visual resultante.

Como o [editor com pré-visualização |https://editor.nette.org/] não tem a opção de guardar alterações diretamente no GitHub, é necessário, após concluir as edições, copiar o texto fonte para a área de transferência (botão *Copy to clipboard*) e depois colá-lo no editor do GitHub. Abaixo do campo de edição existe um formulário para envio. Não se esqueça de resumir brevemente e explicar o motivo da sua modificação. Após o envio, é criado um chamado pull request (PR), que pode ser editado posteriormente.


Modificações Maiores
--------------------

Mais adequado do que usar a interface do GitHub é estar familiarizado com os fundamentos do trabalho com o sistema de controlo de versões Git. Se não domina o trabalho com o Git, pode consultar o guia [git - the simple guide |https://rogerdudler.github.io/git-guide/] e, opcionalmente, usar um dos muitos [clientes gráficos |https://git-scm.com/downloads/guis].

Edite a documentação desta forma:

1) No GitHub, crie um [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] do repositório [nette/docs |https://github.com/nette/docs].
2) [Clone |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] este repositório para o seu computador.
3) Em seguida, no [branch apropriado |#Estrutura da Documentação], faça as alterações.
4) Verifique se há espaços em branco extras no texto usando a ferramenta [Code-Checker |code-checker:].
5) Salve (commit) as alterações.
6) Se estiver satisfeito com as alterações, envie-as (push) para o GitHub no seu fork.
7) A partir daí, envie-as para o repositório `nette/docs` criando um [pull request|https://help.github.com/articles/creating-a-pull-request] (PR).

É comum receber comentários com sugestões. Acompanhe as alterações propostas e incorpore-as. Adicione as alterações propostas como novos commits e envie novamente para o GitHub. Nunca crie um novo pull request para modificar um pull request existente.


Estrutura da Documentação
-------------------------

Toda a documentação está localizada no GitHub no repositório [nette/docs |https://github.com/nette/docs]. A versão atual está no branch `master`, versões mais antigas estão localizadas em branches como `doc-3.x`, `doc-2.x`.

O conteúdo de cada branch é dividido em pastas principais que representam as diferentes áreas da documentação. Por exemplo, `application/` corresponde a `https://doc.nette.org/pt/application`, `latte/` corresponde a `https://latte.nette.org`, etc. Cada uma destas pastas contém subpastas que representam as versões de idioma (`pt`, `en`, `cs`, ...) e, opcionalmente, a subpasta `files` com imagens que podem ser inseridas nas páginas da documentação.

Como Contribuir para a Documentação

Contribuir para a documentação é uma das atividades mais gratificantes, pois ajuda outros a entender o framework.

Como Escrever?

A documentação destina-se principalmente a pessoas que estão a familiarizar-se com o tópico. Portanto, deve cumprir vários pontos importantes:

  • Comece pelo simples e geral. Avance para tópicos mais complexos apenas no final.
  • Tente explicar o assunto da melhor forma possível. Por exemplo, tente explicar primeiro o tópico a um colega.
  • Forneça apenas as informações que o utilizador realmente precisa saber sobre o tópico em questão.
  • Verifique se as suas informações são realmente verdadeiras. Teste cada trecho de código.
  • Seja conciso – reduza o que escreveu pela metade. E depois, se necessário, novamente.
  • Use com moderação todos os tipos de destaque, desde negrito até caixas como .[note].
  • No código, siga os Padrões de Codificação.

Aprenda também a sintaxe. Para pré-visualizar o artigo enquanto o escreve, pode usar o editor com pré-visualização.

Versões de Idioma

O idioma principal é o inglês. As suas alterações devem ser, portanto, em inglês. Se o inglês não for o seu forte, use o DeepL Translator e outros irão rever o seu texto.

A tradução para outros idiomas será feita automaticamente após a aprovação e ajuste da sua modificação.

Modificações Triviais

Para contribuir para a documentação, é essencial ter uma conta no GitHub.

A forma mais fácil de fazer uma pequena alteração na documentação é usar os links no final de cada página:

  • Mostrar no GitHub abre a versão do código-fonte da página no GitHub. Depois, basta pressionar o botão E para começar a editar (é necessário estar autenticado no GitHub).
  • Abrir pré-visualização abre o editor, onde pode ver imediatamente a aparência visual resultante.

Como o editor com pré-visualização não tem a opção de guardar alterações diretamente no GitHub, é necessário, após concluir as edições, copiar o texto fonte para a área de transferência (botão Copy to clipboard) e depois colá-lo no editor do GitHub. Abaixo do campo de edição existe um formulário para envio. Não se esqueça de resumir brevemente e explicar o motivo da sua modificação. Após o envio, é criado um chamado pull request (PR), que pode ser editado posteriormente.

Modificações Maiores

Mais adequado do que usar a interface do GitHub é estar familiarizado com os fundamentos do trabalho com o sistema de controlo de versões Git. Se não domina o trabalho com o Git, pode consultar o guia git – the simple guide e, opcionalmente, usar um dos muitos clientes gráficos.

Edite a documentação desta forma:

  1. No GitHub, crie um fork do repositório nette/docs.
  2. Clone este repositório para o seu computador.
  3. Em seguida, no branch apropriado, faça as alterações.
  4. Verifique se há espaços em branco extras no texto usando a ferramenta Code-Checker.
  5. Salve (commit) as alterações.
  6. Se estiver satisfeito com as alterações, envie-as (push) para o GitHub no seu fork.
  7. A partir daí, envie-as para o repositório nette/docs criando um pull request (PR).

É comum receber comentários com sugestões. Acompanhe as alterações propostas e incorpore-as. Adicione as alterações propostas como novos commits e envie novamente para o GitHub. Nunca crie um novo pull request para modificar um pull request existente.

Estrutura da Documentação

Toda a documentação está localizada no GitHub no repositório nette/docs. A versão atual está no branch master, versões mais antigas estão localizadas em branches como doc-3.x, doc-2.x.

O conteúdo de cada branch é dividido em pastas principais que representam as diferentes áreas da documentação. Por exemplo, application/ corresponde a https://doc.nette.org/pt/application, latte/ corresponde a https://latte.nette.org, etc. Cada uma destas pastas contém subpastas que representam as versões de idioma (pt, en, cs, …) e, opcionalmente, a subpasta files com imagens que podem ser inseridas nas páginas da documentação.