-
-
Notifications
You must be signed in to change notification settings - Fork 88
Open
Labels
ci/cddocumentationrepo managementrelated to organize issues, prs, discussions, sprints, events...related to organize issues, prs, discussions, sprints, events...
Description
Descrição
Atualmente, estamos enfrentando muitos conflitos ao editar os arquivos de documentação, especialmente os README.md
e README_EN.md
. Isso ocorre porque múltiplas pessoas frequentemente estão editando os mesmos arquivos ao mesmo tempo, o que gera conflitos de mesclagem. Como cada novo utilitário ou atualização requer que os documentos sejam modificados, a sobrecarga de resolver esses conflitos tem sido um obstáculo para manter a documentação atualizada de forma eficiente.
Problema
- Conflitos de mesclagem frequentes, pois vários colaboradores editam os mesmos arquivos simultaneamente.
- Dificuldade em gerenciar os conflitos e garantir que a documentação seja atualizada sem perdas de informações ou erros.
Soluções Propostas
Algumas ideias que vieram a cabeça:
-
Dividir a Documentação em Arquivos Menores e Modulares:
- Separar a documentação em arquivos menores e mais específicos para cada utilitário (ex:
cpf.md
,cnpj.md
, etc.), e incluir esses arquivos nosREADME.md
eREADME_EN.md
com um mecanismo de inclusão dinâmica (comoinclude
no Markdown ou utilizando scripts de automação). - Isso evitaria a sobrecarga de edição em arquivos grandes e facilitaria a colaboração, pois as mudanças em um utilitário específico ficariam restritas ao seu próprio arquivo.
- Separar a documentação em arquivos menores e mais específicos para cada utilitário (ex:
-
Usar Arquivos de Configuração YAML para Gerar a Documentação:
- Criar arquivos de configuração YAML para cada utilitário, onde cada arquivo contém as informações sobre as funções e exemplos do utilitário. Esses arquivos serão lidos por um script automatizado que gerará a documentação de forma estruturada.
- A estrutura proposta seria um diretório por utilitário, com arquivos YAML para cada função ou característica do utilitário (ex:
cpf/is_valid.yml
,cpf/format.yml
, etc.). - O script de geração de documentação processaria esses arquivos YAML e geraria automaticamente as entradas para o
README.md
, evitando a edição manual simultânea e garantindo que a documentação esteja sempre atualizada.
Exemplo de Estrutura:
docs/utils/ └── cpf/ └── is_valid.yml └── format.yml └── cnpj/ └── is_valid.yml └── format.yml
Exemplo de arquivo:
cpf: is_valid_cpf: pt-br: title: "is_valid_cpf" description: "Retorna se os dígitos de verificação do CPF fornecido correspondem ao seu número base. Esta função não verifica a existência do CPF; ela apenas valida o formato da string." arguments: cpf: type: "str" description: "O CPF a ser validado, uma string de 11 dígitos" returns: type: "bool" description: "Verdadeiro se os dígitos de verificação corresponderem ao número base, Falso caso contrário." example: | >>> from brutils import is_valid_cpf >>> is_valid_cpf("82178537464") True >>> is_valid_cpf('00011122233') False en: title: "is_valid_cpf" description: "Returns whether the verification digits of the provided CPF match its base number. This function does not verify the existence of the CPF; it only validates the string's format." arguments: cpf: type: "str" description: "The CPF to be validated, a string of 11 digits." returns: type: "bool" description: "True if the verification digits match the base number, False otherwise." example: | >>> from brutils import is_valid_cpf >>> is_valid_cpf("82178537464") True >>> is_valid_cpf('00011122233') False
Passos
- Definir a melhor estratégia, podendo ser uma das abordagens propostas ou outra nova. Favor discutir a ideia aqui na issue antes da implementação.
- Implementar a automação para ler os arquivos YAML e gerar a documentação automaticamente.
- Testar as automações para garantir que estão funcionando corretamente.
- Garantir que o arquivo
README.md
preserve o conteúdo gerado até então, mantendo o seu padrão atual. Ou seja, o resultado final deve ser o mesmo, mas o processo de geração dele deve ser adaptado. - Atualizar as documentações de contribuição:
Impacto Esperado
- Redução de conflitos de mesclagem na documentação.
- Melhor organização da documentação com maior modularidade.
- Processo de contribuição mais eficiente e sem sobrecarga para os colaboradores.
Metadata
Metadata
Assignees
Labels
ci/cddocumentationrepo managementrelated to organize issues, prs, discussions, sprints, events...related to organize issues, prs, discussions, sprints, events...