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 nos README.md e README_EN.md com um mecanismo de inclusão dinâmica (como include 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.
-
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.
Descrição
Atualmente, estamos enfrentando muitos conflitos ao editar os arquivos de documentação, especialmente os
README.mdeREADME_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
Soluções Propostas
Algumas ideias que vieram a cabeça:
Dividir a Documentação em Arquivos Menores e Modulares:
cpf.md,cnpj.md, etc.), e incluir esses arquivos nosREADME.mdeREADME_EN.mdcom um mecanismo de inclusão dinâmica (comoincludeno Markdown ou utilizando scripts de automação).Usar Arquivos de Configuração YAML para Gerar a Documentação:
cpf/is_valid.yml,cpf/format.yml, etc.).README.md, evitando a edição manual simultânea e garantindo que a documentação esteja sempre atualizada.Exemplo de Estrutura:
Exemplo de arquivo:
Passos
README.mdpreserve 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.Impacto Esperado