DeepDocs: a ferramenta de IA do GitHub que atualiza automaticamente a documentação do código

O DeepDocs é uma ferramenta de IA baseada no GitHub focada em resolver o problema de atualizações incômodas da documentação do código. Ao analisar de forma inteligente as alterações de código, ele atualiza automaticamente a documentação do projeto, como READMEs, referências de API e tutoriais, para garantir que ela permaneça sincronizada com o código. O DeepDocs se integra aos fluxos de trabalho do GitHub sem a necessidade de uma plataforma adicional, o que o torna ideal para equipes de desenvolvimento rápido. Ele examina toda a base de código, identifica a documentação desatualizada e a atualiza com precisão, sem alterar seu formato ou estilo. Com uma configuração simples, os usuários podem automatizar o gerenciamento de documentos, reduzindo a necessidade de manutenção manual, e o DeepDocs enfatiza a privacidade, pois o código é processado apenas temporariamente em tempo de execução e não é armazenado.

Lista de funções

• Atualizações contínuas de documentaçãoDetectar e atualizar automaticamente os documentos afetados após cada confirmação de código.
• varredura profundaAnálise completa da base de código e correção em lote de toda a documentação desatualizada.
• editor inteligente (software)Atualize apenas as partes necessárias do documento, mantendo a estrutura e o estilo originais.
• Relatório detalhadoGerar um relatório de alterações descrevendo o motivo da atualização da documentação e o commit do código associado.
• Integração nativa do GitHubIncorporado diretamente nos fluxos de trabalho do GitHub para criar um ramo separado para fazer o commit de atualizações de documentos.
• Suporte a vários tipos de documentosCompatível com READMEs, referências de API, guias de SDK, tutoriais e muito mais.
• PrivacidadeProcessamento de código: o processamento de código é temporário e não é armazenado, garantindo a segurança dos dados.

Usando a Ajuda

Processo de instalação

O DeepDocs é muito fácil de instalar e configurar para qualquer equipe de desenvolvimento que use o GitHub. Aqui estão as etapas detalhadas de instalação:

1. Instalando o aplicativo DeepDocs GitHub
   Abra seu repositório do GitHub e vá para Settings > GitHub Apps. Pesquisar no GitHub Marketplace DeepDocsAIClique em Configure. Selecione o repositório de código que precisa ser monitorado (se a documentação estiver em um repositório separado, ela também precisará ser instalada nesse repositório). Clique em Save Salve a configuração. Se precisar adicionar mais repositórios, você poderá fazer isso mais tarde no Installation Settings Ajuste médio.
2. Criação de arquivos de configuração
   Crie um arquivo no diretório raiz do repositório de código chamado deepdocs.yml arquivo. A seguir, um exemplo de uma configuração básica:

   target:
   - url: "docs/"
   reinit: "random-string"
   ignore: []
   

   • targetEspecifique a pasta do documento ou o caminho do arquivo a ser monitorado, por exemplo. docs/.
   • reinitSequência de caracteres aleatória usada para acionar manualmente uma varredura de profundidade.
   • ignoreEspecificar arquivos ou pastas a serem ignorados (opcional).
     Faça o commit desse arquivo na ramificação a ser monitorada (por exemplo main talvez dev).
3. Acionar varredura inicial
   apresentar (um relatório etc.) deepdocs.yml Depois disso, o DeepDocs aciona automaticamente uma varredura profunda que analisa toda a base de código e atualiza a documentação desatualizada. Os resultados são confirmados em uma nova ramificação chamada deepdocs-deepscan-<branch>-<commit_sha>com um relatório atualizado.

Uso das funções principais

Atualizações contínuas de documentação

O principal recurso do DeepDocs é a atualização contínua da documentação. Após cada commit de código (push ou pull request), o DeepDocs verifica automaticamente o código em busca de alterações e determina qual documentação precisa ser atualizada. Por exemplo, se um endpoint de API for modificado, o DeepDocs atualizará a documentação de referência da API relevante. As atualizações são confirmadas em um novo branch (por exemplo, o branch deepdocs-update-<branch>-<commit_sha>) que contêm relatórios detalhados de alterações. Os usuários podem revisar e mesclar essas atualizações diretamente no GitHub.

varredura profunda

A digitalização profunda é adequada para lidar com um grande número de documentos obsoletos. Os usuários podem modificar a deepdocs.yml acertou em cheio reinit O DeepDocs examina toda a base de código, identifica todos os documentos que precisam ser atualizados e gera uma ramificação contendo todas as alterações. O relatório lista os documentos atualizados, o motivo da alteração e os commits de código associados.

Edição e relatórios inteligentes

O DeepDocs usa IA para analisar o código em relação à documentação, atualizando apenas as partes necessárias. Por exemplo, se uma assinatura de função for alterada, o DeepDocs atualiza apenas a descrição da documentação associada sem reescrever o arquivo inteiro. Cada atualização gera um relatório que descreve quais documentos foram alterados, por que e os commits de código associados. Isso permite que as equipes verifiquem rapidamente a precisão das atualizações.

Integração nativa do GitHub

O DeepDocs é incorporado diretamente nos fluxos de trabalho do GitHub sem ferramentas adicionais. Ele é executado por meio do GitHub Actions e monitora pull requests e commits de código. A documentação atualizada é enviada como uma solicitação pull, facilitando a revisão pelas equipes. Os usuários podem fazer tudo sem sair do GitHub.

fluxo de trabalho

1. Enviar códigoDesenvolvedores: Normalmente, os desenvolvedores enviam o código para os repositórios do GitHub.
2. detecção automáticaDeepDocs: O DeepDocs detecta alterações no código e analisa o impacto na documentação.
3. Gerar atualizaçõesDeepDocs: O DeepDocs faz o commit da documentação e dos relatórios atualizados na nova ramificação.
4. Revisão e consolidaçãoA equipe analisa o pull request no GitHub, confirma-o e faz o merge.
5. Varredura manual de profundidade(Opcional): Modificar reinit que aciona uma correção completa do documento.

advertência

• Se os documentos e o código estiverem em repositórios diferentes, certifique-se de que o aplicativo DeepDocs esteja instalado em ambos os repositórios, mas configure apenas o repositório de código com deepdocs.yml.
• O DeepDocs não gera um documento totalmente novo, ele requer um documento inicial (por exemplo, por meio do Copiloto do GitHub (Criado).
• As atualizações da documentação respeitam o formato Markdown original, adequado para projetos de código aberto ou equipes internas.

cenário do aplicativo

1. Manutenção de projetos de código aberto
   O DeepDocs sincroniza automaticamente a documentação, reduzindo a carga sobre os mantenedores para atualizá-la manualmente e garantindo que os novos desenvolvedores possam entender rapidamente o código e as APIs mais recentes.
2. Equipe de desenvolvimento iterativo rápido
   O DeepDocs atualiza automaticamente o README e a documentação da API, permitindo que as equipes se concentrem na codificação e mantenham a documentação precisa.
3. Gerenciamento de projetos de vários armazéns
   O DeepDocs oferece suporte à sincronização entre repositórios para grandes projetos em que o código e os documentos são armazenados separadamente. Ele monitora as alterações no repositório de código e atualiza o conteúdo no repositório de documentos para equipes de arquitetura de microsserviços.
4. Liquidação de dívidas técnicas
   Os projetos mais antigos geralmente têm muita documentação desatualizada, e o recurso de varredura profunda do DeepDocs corrige tudo isso de uma vez, gerando relatórios de alteração claros que ajudam as equipes a limpar rapidamente seu débito técnico.

QA

1. O DeepDocs altera a formatação ou o estilo do documento?
   Não. O DeepDocs atualiza apenas a parte da documentação relacionada à alteração do código, preservando a formatação, o tom e a estrutura originais.
2. Que tipos de documentos são compatíveis com o DeepDocs?
   Oferece suporte à documentação no formato Markdown, incluindo READMEs, referências de API, guias de SDK e tutoriais, adequados para a maioria das documentações técnicas.
3. Como aciono uma varredura profunda?
   modificações deepdocs.yml acertou em cheio reinit e commit, o DeepDocs examina toda a base de código e atualiza a documentação desatualizada.
4. O DeepDocs armazena meu código?
   Não. O DeepDocs processa apenas temporariamente o código em tempo de execução e não o armazena após o processamento, garantindo privacidade e segurança.
5. O DeepDocs exige documentação inicial?
   Sim. O DeepDocs não gera documentação totalmente nova, ele precisa ter a documentação inicial primeiro. Ele se concentra em manter a documentação existente em sincronia com o código.