Conflitos Frequentes de Edição nos Arquivos de README

[camilamaia]

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:

1. 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.

2. 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:
  • [Instruções em português](https://github.com/brazilian-utils/brutils-python/blob/main/CONTRIBUTING.md#12-adicione-entradas-no-changelogmd)
  • [Instruções em inglês](https://github.com/brazilian-utils/brutils-python/blob/main/CONTRIBUTING_EN.md#12-add-changelog-entries)

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.

[tiagornandrade]

boral!

[tiagornandrade]

Com base nas soluções propostas eu acredito que a melhor abordagem é a geração automática da documentação utilizando arquivos YAML, pois:

• Evita conflitos de edição simultânea ao separar a documentação por função/utilitário.
• Garante padronização ao centralizar a estrutura da documentação em arquivos estruturados.
• Reduz o trabalho manual ao gerar os arquivos README.md e README_EN.md de forma automatizada.

Daí a documentação será organizada da seguinte forma:

exemplo:
docs/utils/
└── cpf/
└── is_valid.yml
└── format.yml
└── cnpj/
└── is_valid.yml
└── format.yml

Cada arquivo YAML conterá a documentação de um utilitário específico, em múltiplos idiomas, incluindo título, descrição, argumentos, retorno e exemplos.