Nette Documentation Preview

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

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.