Documentação
Esta documentação é nosso principal canal de comunicação e a única fonte de verdade para todo o material sobre o projeto. Ajudar na evolução da documentação é tão importante quanto na evolução do próprio código.
Existem algumas formas de ajudar:
- Crie ou atualize: Crie ou atualize a documentação
- Traduzindo: Ajude-nos a manter a tradução atualizada
Tópicos sobre partes especiais da documentação:
- API de componentes: A documentação da API dos componentes é gerada automaticamente por um script usando um modelo.
Criando ou atualizando um conteúdo
Antes de tudo, você precisa ter conhecimento sobre Git e os conceitos básicos do GitHub, para trabalhar com o Tangram. Você tem dois caminhos:
- Não sei e não quero aprender Git. Neste caso, crie uma issue aqui e peça para um dos mantenedores criar ou atualizar a página em questão.
- Eu sei, ou posso lidar com isso. Excelente! Então siga o passo a passo abaixo.
Configurando o ambiente
Se você não está acostumado a trabalhar com Git e GitHub, você pode usar o HackMD que é um editor de markdown que já possui integração com o GitHub, então você pode use-o diretamente do seu navegador sem precisar instalar nada em sua máquina.
Caso contrário, com o Git já instalado, você pode clonar o projeto:
git clone git@github.com:ResultadosDigitais/tangram.git
Nova branch
Crie uma nova branch para que você possa fazer suas alterações com segurança e depois enviá-las para revisão. Através do terminal isso pode ser feito através do comando:
cd tangram
git checkout -b my-new-branch
Altere o my-new-branch com o nome da sua branch. O nome da branch são palavras separadas por hífens, geralmente é uma breve descrição do que se trata a mudança, por exemplo: add-testing-guide, translate-drawer-doc.
Escrevendo
A documentação está dividida em 3 diretórios: docs/code, docs/docs e docs/examples e cada um desses diretórios tem uma responsabilidade.
Caso seja necessário criar a documentação de um componente a criação dos arquivos deve ser nos diretórios docs/docs (com texto sobre o uso do componente) e docs/examples (com os exemplos de uso do componente).
Se você quiser adicionar uma página mais genérica, que faça parte das outras categorias da documentação você deve criar ela dentro do diretório docs/docs, na pasta correspondente.
O diretório docs/code não precisa ser alterado pois ele os arquivos contidos la são gerados de forma automática.
O texto deve ser escrito em inglês e em portugês, acesse o tópico Traduzindo para obter mais detalhes sobre como atualizar a tradução.
Todos os cabeçalhos devem ter IDs explícitos para manter o link entre todas as traduções. Você pode criá-los manualmente, ou pode sair sem e no final usar o seguinte script para gerá-los automaticamente:
yarn docs write-heading-ids
Criando o pull request
Com todas as alterações feitas, agora é a hora de criar um pull request para os mantenedores do Tangram revisarem.
Se você ainda não confirmou suas alterações, faça isso com o comando:
git add file1 file2
git commit -m "docs: description about the changes"
Leia sobre nosso padrão de mensagem de confirmação aqui.
Em seguida, envie suas alterações para o GitHub:
git push -u origin my-new-branch
Altere o my-new-branch com o nome da branch que você acabou de criar. A saída do comando fornecerá um URL para criar o pull request, clique nele para fazer isso.
Com a página aberta para criar o pull request, adicione o rótulo da versão. Como você está alterando a documentação, escolha o rótulo tag:documentation.
O título será preenchido da mesma forma que você definiu ao criar a branch. Se estiver bem escrito, não precisa mudar.
Na descrição é onde você entra nos detalhes da mudança para dar contexto aos revisores. O Tangram já possui um template, então é só ler e seguir as orientações.
Por fim, basta clicar no botão "Criar pull request" para criá-la. Em seguida, espere que um dos mantenedores do projeto revise sua solicitação e interaja com você na própria pull request.
Traduzindo
Embora o Docusaurus forneça suporte nativo para internacionalização, nosso processo de tradução ainda é bastante manual.
Primeiro, confirme se todos os cabeçalhos têm id explícito:
yarn docs write-heading-ids
IDs explícitos garantirão que o link para os títulos seja o mesmo entre as traduções.
Em seguida, execute o script para escrever as chaves de tradução ainda não concluídas:
yarn docs write-translations
Agora é só acessar os arquivos de tradução no diretório docs/i18n/pt-BR e segue o mesmo padrão de estrutura de diretórios comentado em um dos tópicos acima.
Para iniciar seu site localizado no modo dev:
yarn docs start:br
Cada idioma é uma aplicação única e independente, ou seja, não é possível iniciar o Docusaurus em todos idiomas ao mesmo tempo.
API do componente
O script deve ser executado toda vez que você precisar atualizar a documentação. Mas você pode executá-lo enquanto o Docusaurus estiver em execução e ele reconhecerá as novas alterações.
A documentação da API do componente é gerada automaticamente usando o seguinte comando:
yarn docs write-components-api
yarn docs write-hooks-api
A documentação da API só será gerada para os componentes listados no arquivo docs/sidebars/sidebars.js, no array COMPONENTS_CATEGORY. O item da matriz deve incluir o ID da guia "api". Exemplo:
const COMPONENTS_CATEGORY = [
{
label: 'Component1',
// The "docs" must to be in docs/docs/components/component1.md
path: 'components/component1',
tabs: ['docs', 'api']
},
{
label: 'Component2',
// The "docs" must to be in docs/docs/components/component2.md
path: 'components/component2',
tabs: ['docs']
}
];
No exemplo acima, o script tentará gerar a documentação da API apenas para Component1, pois foi o único indicado que terá a aba "api".
Este componente deve estar no diretório packages/components/src/component1/ (extração lógica da propriedade path), e a documentação será gerada no arquivo docs/code/components/component1.md.
Todas as informações são retiradas dos comentários do próprio componente. O comentário deve seguir o padrão JSDoc, desta forma a documentação é feita apenas uma vez e é reutilizada para:
- o próprio código, facilita a manutenção e evolução do código
- é exportado no contrato lib, usando o Tangram como lib é possível usar a documentação diretamente do editor de código
- usado nesta documentação
Block tags
O script não exclui um arquivo markdown já criado, você precisa excluir manualmente o arquivo, se for o caso.
O script reconhece as seguintes tags de bloco:
@ignore
Você pode ignorar uma propriedade para que ela não apareça na documentação:
MyComponent.propTypes = {
/**
* @ignore
* Sets the children
*/
children: PropTypes.node
};
Ou você pode ignorar todo o componente:
/**
* @ignore
*/
function MyComponent() {}
@deprecated
Você pode relatar que uma determinada propriedade está depreciada:
MyComponent.propTypes = {
/**
* @deprecated since version 2
* Sets the icon on the left side of the text
*/
icon: PropTypes.node
};
A descrição da tag é opcional.
@param and @returns
Para o caso de uma propriedade que é uma função, é possível utilizar as tags @param e @returns, confira sua documentação para saber como definir sua sintaxe.
@example
Você pode incluir exemplos adicionais com @example para ilustrar o uso da propriedade:
MyComponent.propTypes = {
/**
* Sets all options displayed by the menu.
* @example
* const options = [{value: 1, label: 'Joel'}, {value: 2, label: 'Ellie'}]
* */
options: PropTypes.arrayOf(PropTypes.shape({}))
};
O exemplo será exibido dentro de um bloco de código usando a linguagem JSX para o realce da sintaxe.
@since
Ao adicionar uma nova propriedade, certifique-se de especificar qual versão usando a tag @since:
MyComponent.propTypes = {
/**
* Sets all options displayed by the menu.
* @since 1.0.1
* */
options: PropTypes.arrayOf(PropTypes.shape({}))
};