autodoc

O que é isso? • Começar • Comunidade • Contribuir

O que é isso?

Autodoc é um kit de ferramentas experimental para geração automática de documentação de base de código para repositórios git usando modelos de linguagem grandes, como GPT-4 ou Alpaca. O Autodoc pode ser instalado em seu repositório em cerca de 5 minutos. Ele indexa sua base de código por meio de uma travessia profunda de todo o conteúdo do repositório e chama um LLM para escrever documentação para cada arquivo e pasta. Esses documentos podem ser combinados para descrever os diferentes componentes do seu sistema e como eles funcionam juntos.

A documentação gerada reside em sua base de código e viaja para onde seu código viaja. Os desenvolvedores que baixam seu código podem usar o comando doc para fazer perguntas sobre sua base de código e obter respostas altamente específicas com links de referência para arquivos de código.

Num futuro próximo, a documentação será reindexada como parte do seu pipeline de CI, para que esteja sempre atualizada. Se você tem interesse em trabalhar contribuindo com este trabalho, veja esta edição.

Status

O Autodoc está nos estágios iniciais de desenvolvimento. Está funcional, mas não está pronto para uso em produção. As coisas podem quebrar ou não funcionar como esperado. Se você estiver interessado em trabalhar na estrutura principal do Autodoc, consulte contribuir. Adoraríamos ter sua ajuda!

Perguntas frequentes

Pergunta: Não estou obtendo boas respostas. Como posso melhorar a qualidade da resposta?

Resposta: O Autodoc está nos estágios iniciais de desenvolvimento. Como tal, a qualidade da resposta pode variar amplamente com base no tipo de projeto que você indexa e em como as perguntas são formuladas. Algumas dicas para escrever uma boa consulta:

1. Seja específico com suas perguntas. Pergunte coisas como "Quais são os diferentes componentes de autorização neste sistema?" em vez de "explicar autenticação". Isso ajudará o Autodoc a selecionar o contexto certo para obter a melhor resposta para sua pergunta.
2. Use GPT-4. O GPT-4 é substancialmente melhor na compreensão do código em comparação com o GPT-3.5 e esse entendimento também é transferido para a escrita de boa documentação. Caso não tenha acesso, cadastre-se aqui.

Exemplos

Abaixo estão alguns exemplos de como o Autodoc pode ser usado.

1. Autodoc - Este repositório contém documentação própria, gerada pelo Autodoc. Ele fica na pasta .autodoc . Siga as instruções aqui para saber como consultá-lo.
2. TolyGPT.com - TolyGPT é um chatbot Autodoc treinado na base de código do validador Solana e implantado na web para fácil acesso. Num futuro próximo, o Autodoc oferecerá suporte a uma versão web além da ferramenta CLI existente.

Comece

Requisitos

Autodoc requer Node v18.0.0 ou superior. v19.0.0 ou superior é recomendado. Certifique-se de estar executando a versão correta:

$ node -v

Exemplo de saída:

v19.8.1

Instale a ferramenta Autodoc CLI como um módulo NPM global:

$ npm install -g @context-labs/autodoc

Este comando instala a ferramenta Autodoc CLI que permitirá criar e consultar índices Autodoc.

Execute doc para ver os comandos disponíveis.

Consultando

Você pode consultar um repositório que tenha o Autodoc instalado por meio da CLI. Usaremos o próprio repositório do Autodoc como exemplo para demonstrar como funciona a consulta no Autodoc, mas este pode ser o seu próprio repositório que contém um índice.

Clone o Autodoc e altere o diretório para começar:

$ git clone https://github.com/context-labs/autodoc.git
$ cd autodoc

No momento, o Autodoc oferece suporte apenas a OpenAI. Certifique-se de ter sua chave de API OpenAI exportada em sua sessão atual:

$ export OPENAI_API_KEY= < YOUR_KEY_HERE >

Para iniciar a CLI de consulta do Autodoc, execute:

$ doc q

Se esta for a primeira vez que você executa doc q , você verá uma tela solicitando que você selecione a quais modelos GPT você tem acesso. Selecione o que for apropriado para o seu nível de acesso. Se não tiver certeza, selecione a primeira opção:

Agora você está pronto para consultar a documentação do repositório Autodoc:

Esta é a principal experiência de consulta. É muito básico agora, com muito espaço para melhorias. Se você estiver interessado em melhorar a experiência de consulta da CLI do Autodoc, verifique este problema.

Indexação

Siga as etapas abaixo para gerar documentação para seu próprio repositório usando Autodoc.

Mude o diretório para a raiz do seu projeto:

 cd $PROJECT_ROOT

Certifique-se de que sua chave da API OpenAI esteja disponível na sessão atual:

$ export OPENAI_API_KEY= < YOUR_KEY_HERE >

Execute o comando init :

 doc init

Você será solicitado a inserir o nome do seu projeto, o URL do GitHub e selecionar a quais modelos GPT você tem acesso. Se você não tiver certeza de quais modelos tem acesso, selecione a primeira opção. Você também pode especificar seus próprios prompts de arquivo/diretório GPT que serão usados ​​para resumir/analisar o repositório de código. Este comando gerará um arquivo autodoc.config.json na raiz do seu projeto para armazenar os valores. Este arquivo deve ser verificado no git.

Nota: Não pule a inserção desses valores ou a indexação poderá não funcionar.

Configuração do prompt: você encontrará instruções de prompt especificadas em prompts.ts , com alguns trechos personalizáveis ​​em autodoc.config.json . Os prompts atuais são focados no desenvolvedor e assumem que seu repositório é focado no código. Teremos mais modelos de referência no futuro.

Execute o comando index :

doc index

Você deverá ver uma tela como esta:

Esta tela estima o custo de indexação do seu repositório. Você também pode acessar esta tela através do comando doc estimate . Se você já indexou uma vez, doc index reindexará apenas os arquivos que foram alterados na segunda vez.

Para cada arquivo do seu projeto, o Autodoc calcula o número de tokens no arquivo com base no conteúdo do arquivo. Quanto mais linhas de código, maior será o número de tokens. Usando esse número, ele determina qual modelo será usado por arquivo, sempre escolhendo o modelo mais barato cujo comprimento de contexto suporta o número de tokens no arquivo. Se você estiver interessado em ajudar a tornar a seleção de modelos configurável no Autodoc, confira esta edição.

Observação: essa estratégia ingênua de seleção de modelo significa que arquivos com menos de 4.000 tokens serão documentados usando GPT-3.5, o que resultará em uma documentação menos precisa. Recomendamos o uso mínimo de GPT-4 8K. A indexação com GPT-4 resulta em resultados significativamente melhores. Você pode solicitar acesso aqui.

Para grandes projetos, o custo pode chegar a várias centenas de dólares. Veja os preços do OpenAI aqui.

Num futuro próximo, daremos suporte a modelos auto-hospedados, como Llama e Alpaca. Leia esta edição se você tiver interesse em contribuir para este trabalho.

Quando o seu repositório terminar de ser indexado, você deverá ver uma tela como esta:

Agora você pode consultar seu aplicativo usando as etapas descritas em consulta.

Comunidade

Há um pequeno grupo de nós que trabalha em tempo integral no Autodoc. Junte-se a nós no Discord ou siga-nos no Twitter para atualizações. Estaremos postando regularmente e continuando a melhorar o aplicativo Autodoc. Quer contribuir? Leia abaixo.

Contribuindo

Como um projeto de código aberto em um campo em rápido desenvolvimento, estamos extremamente abertos a contribuições, seja na forma de um novo recurso, infra-estrutura aprimorada ou melhor documentação.

Para informações detalhadas sobre como contribuir, veja aqui.