Gerar documentação do projeto usando GitHub Copilot

  • 6 minutos

A documentação do projeto descreve a finalidade, as metas e os requisitos de um projeto. Para criar a documentação do projeto, você precisa entender a estrutura do projeto, seus componentes e como os componentes interagem entre si.

O modo de exibição de Chat do GitHub Copilot é uma ferramenta ideal para gerar a documentação do projeto, pois pode analisar toda a estrutura do projeto e fornecer visões gerais de alto nível do projeto. O modo de exibição de Chat também pode ser usado para gerar tipos específicos de documentação, como arquivos README, referências de API e outros documentos relacionados ao projeto.

Você pode usar cada um dos modos de exibição de chat (Pergunte, Agente ou Plano) para gerar a documentação do projeto. Cada modo tem seus próprios pontos fortes e fracos. As especificações do projeto e outras restrições afetam qual modo deve ser usado.

Importante

Quando você usa a exibição chat no modo de agente, cada prompt que você insere conta como uma solicitação premium, multiplicada pelo multiplicador do modelo. GitHub Copilot pode executar várias ações de acompanhamento para concluir sua tarefa, mas essas ações de acompanhamento não contam para o uso da solicitação premium. Somente as solicitações que você inserir serão cobradas. O total de solicitações premium usadas depende de quantos prompts você inserir e de qual modelo for selecionado.

Estabelecer requisitos de documentação do projeto

Os tipos de documentação e os requisitos de conteúdo dependem do projeto, dos consumidores pretendidos e dos padrões adotados pela organização.

Por exemplo, o README.md pode incluir as seguintes seções:

  • Título do projeto: o nome do seu projeto.
  • Descrição: uma breve visão geral do que o projeto faz e por que ele existe.
  • Sumário: opcional, mas útil para READMEs mais longos.
  • Instalação: instruções sobre como instalar e configurar o projeto.
  • Uso: exemplos de como usar o projeto, incluindo snippets de código ou capturas de tela.
  • Recursos: uma lista dos principais recursos ou funcionalidades.
  • Configuração: detalhes sobre as opções de configuração ou variáveis de ambiente.
  • Contribuindo: diretrizes para contribuir com o projeto.
  • Licença: todas as licenças usadas pelo projeto distribuído.
  • Créditos e confirmações: reconhecimento de colaboradores, bibliotecas ou recursos usados.
  • Contato: Como acessar os mantenedores ou a equipe de projeto.
  • Changelog: um histórico de alterações e atualizações (às vezes vinculado a um arquivo separado).

GitHub Copilot Chat pode ajudá-lo a gerar a documentação do projeto que atenda às necessidades específicas do seu projeto e de seus stakeholders.

Usar o modo do agente Ask para gerar a documentação do projeto

O modo do agente Ask pode ser usado para analisar um workspace e, em seguida, gerar documentação.

Use o seguinte processo para gerar a documentação do projeto usando o modo do agente Ask:

  1. Identifique os requisitos de documentação e os recursos de suporte.

    • Identifique os requisitos de documentação do projeto. Identifique os tipos de documentação e as seções de documento necessárias.

    • Identifique os recursos necessários para gerar a documentação. Seu ambiente de codificação pode ser o único recurso necessário. No entanto, talvez seja necessário adicionar contexto ao chat para seções como "Contribuindo", "Créditos" e "Contato".

  2. Abra a janela de chat e inicie uma nova sessão de chat usando o modo agente Ask.

  3. Adicione contexto à sessão de chat.

    • Você pode adicionar contexto à sessão de bate-papo arrastando e soltando arquivos da vista EXPLORER do Visual Studio Code na vista do Chat. Você também pode usar o botão Anexar Contexto (ícone de clipe de papel).
    • Você pode abrir arquivos externos no editor de código para incluir recursos que não fazem parte do workspace e usá-los para fornecer mais contexto. Por exemplo, você pode abrir arquivos markdown que contêm diretrizes de colaborador ou informações de contato e, em seguida, usar o botão Anexar Contexto para adicioná-los ao contexto de exibição de Chat.

  4. Insira uma série de prompts que investiguem seus requisitos de documentação.

    Você pode usar o modo Ask agent para analisar o espaço de trabalho e criar um histórico de sessão de chat que apoie seus requisitos de documentação. Descrever suas metas pode ajudar a estabelecer o contexto para a sessão de chat. Fazer perguntas que abordam seus requisitos ajuda GitHub Copilot identificar as informações necessárias para gerar a documentação.

    Atualize o contexto adicionado conforme necessário.

  5. Insira um prompt que solicita a documentação sugerida do projeto, listando as seções necessárias que você identificou na primeira etapa.

    Por exemplo: "@workspace /explain I need help creating a README file that can be used in the GitHub repository for this workspace. The file should be formatted as markdown. The README file needs to include the following sections: Project Title, Description, Table of Contents, Installation, Usage, Features, Configuration, and License."

  6. Revise a documentação sugerida do projeto e refine os resultados usando novos comandos, se necessário.

  7. Mova a documentação sugerida do projeto para um arquivo de documentação do projeto.

    Por exemplo, crie um arquivo README.md na raiz do workspace e insira o conteúdo sugerido no arquivo.

    Você pode usar o modo Solicitar agente para sugerir atualizações para seções específicas do seu projeto depois de criar o documento ou usar outras ferramentas GitHub Copilot para ajudar nas atualizações.

Usar o modo Plano para gerar a documentação do projeto

O modo de plano é melhor para criar um plano de implementação detalhado antes de gerar a documentação do projeto. O modo Plano analisa a base de código, identifica os requisitos de documentação e produz um plano passo a passo. Depois que o plano for aprovado, você poderá entregá-lo ao modo de agente para execução.

Use o seguinte processo para gerar a documentação do projeto, como um arquivo README.md, usando o modo Plano:

  1. Identifique os requisitos de documentação e os recursos de suporte.

  2. Abra a visualização de chat e inicie uma nova sessão de chat usando o modo Planejamento.

  3. Insira um prompt que descreve sua tarefa de documentação.

    Por exemplo: "Preciso criar um arquivo README e a documentação de suporte para este projeto. O LEIAME deve incluir: Título do Projeto, Descrição, Sumário, Instalação, Uso, Recursos, Configuração e Licença."

  4. Examine o plano de implementação.

    Após alguns instantes, o agente de planejamento exibirá um plano na visualização de bate-papo. O plano fornece um resumo de alto nível e um detalhamento das etapas, incluindo quaisquer perguntas abertas para esclarecimentos. Você pode iterar várias vezes para esclarecer os requisitos, ajustar o escopo ou responder a perguntas.

  5. Depois que o plano for concluído, selecione Iniciar Implementação para entregar o plano ao modo de agente ou selecione Abrir no Editor para salvar o plano como um arquivo Markdown para uso posterior.

    Quando você seleciona Start Implementation, GitHub Copilot alterna para o modo de agente e começa a implementar a documentação com base no plano aprovado. Examine os arquivos de documentação gerados e aceite ou descarte as alterações.

Usar o modo de agente para gerar a documentação do projeto

O modo de agente é melhor para gerar a documentação do projeto que requer uma compreensão detalhada do projeto. O modo de agente analisa toda a estrutura do projeto antes de gerar a documentação do projeto. Ao coletar informações de vários arquivos e pastas, o modo de agente pode descrever relações complexas e incluir links entre documentos.

Use o seguinte processo para gerar a documentação do projeto, como README.md arquivo, usando o modo de agente:

  1. Identifique os requisitos de documentação e os recursos de suporte.

  2. Abra o modo de exibição chat e inicie uma nova sessão de chat usando o modo de agente.

  3. Adicione contexto à sessão de chat.

    Os participantes do chat não estão disponíveis no modo de agente, portanto, você não pode especificar @workspace como parte do prompt. No entanto, você pode adicionar contexto à sessão de chat usando #codebase e adicionando arquivos e pastas de workspace ao contexto de chat. Os arquivos externos podem ser abertos em Visual Studio Code e, em seguida, adicionados ao contexto de chat usando o botão Anexar Contexto.

  4. Insira um prompt para criar a documentação do projeto pretendida.

    Por exemplo: "Gerar uma coleção de arquivos de documentação do projeto. Crie ou atualize o workspace README.md arquivo para este repositório. Crie ou atualize o arquivo UsageExamples.md. Crie ou atualize o arquivo ChangeLog.md. Inclua links entre os arquivos de documentação, classes e métodos de referência cruzada e garanta a consistência entre os documentos."

  5. Examine os arquivos do documento e salve ou descarte as atualizações.

    Atualize o arquivo usando prompts para corrigir ou aprimorar seções específicas, se necessário.

Funcionalidades do modo de agente

Há várias tarefas de documentação em que o modo de agente é a melhor opção.

  1. Geração de documentação para vários arquivos e entre arquivos.

    • O modo de agente pode analisar toda a estrutura do projeto, coletar informações de vários arquivos e pastas e gerar documentação que vincula e resume o conteúdo na base de código. Por exemplo, gerar uma referência de API completa ou um README que descreve todos os componentes principais.

  2. Análise e resumização automatizadas de projeto.

    • O modo de agente pode executar tarefas como resumir a arquitetura, identificar classes/serviços principais e produzir diagramas ou tabelas que exigem a compreensão das relações entre arquivos e componentes.

  3. Geração dinâmica de conteúdo (por exemplo, exemplos de uso, tabelas de classe)

    • O modo de agente pode verificar o projeto para gerar exemplos de uso, tabelas de responsabilidade de classe ou listas de APIs públicas.

  4. Tarefas de documentação em lote

    • O modo de agente pode executar uma sequência de tarefas de documentação (por exemplo, atualizar README, criar CONTRIBUTING.md, gerar documentos de API, atualizar o changelog) em um fluxo de trabalho.

  5. Vinculação inteligente e navegação.

    • O modo de agente pode criar links entre arquivos de documentação, classes e métodos de referência cruzada e garantir a consistência entre documentos.

O modo de agente é ideal para tarefas de documentação em todo o projeto, com vários arquivos e com reconhecimento de contexto que exigem análise, síntese e coordenação.

Resumo

GitHub Copilot pode ajudá-lo a gerar a documentação do projeto que atenda às necessidades específicas do seu projeto e de seus stakeholders. A Visualização de Chat pode ser usada para gerar a documentação do projeto em três modos diferentes: Perguntar, Agente e Planejar. Cada modo tem seus próprios pontos fortes e fracos, e o melhor modo a ser usado depende da tarefa específica em questão. O modo do agente Ask é melhor para fazer perguntas sobre sua base de código ou conceitos de tecnologia. O modo agent é melhor para gerar a documentação do projeto que requer uma compreensão detalhada do projeto. O modo Plano é melhor para criar um plano de implementação detalhado antes de gerar a documentação, que pode ser entregue ao modo agent para execução.