Gerar documentação do projeto usando o 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.

A exibição de Chat do GitHub Copilot é uma ferramenta ideal para gerar 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, Editar ou Agente) 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, o GitHub Copilot pode fazer várias solicitações premium para concluir uma única tarefa. Solicitações Premium podem ser usadas por prompts iniciados pelo usuário e ações de acompanhamento que o Copilot realiza em seu nome. O total de solicitações premium usadas depende da complexidade da tarefa, do número de etapas envolvidas e do modelo 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).

O 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 de solicitação para gerar a documentação do projeto

O modo de solicitação 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 de solicitação:

  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 o modo de exibição chat e inicie uma nova sessão de chat usando o modo de solicitação.

  3. Adicione contexto à sessão de chat.

    • Você pode adicionar contexto à sessão de chat arrastando e soltando arquivos da exibição EXPLORER do Visual Studio Code na exibição Chat. Você também pode usar o botão Adicionar Contexto .
    • 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 Adicionar 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 de solicitação para analisar o workspace e criar um histórico de sessão de chat que dê suporte aos 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 o GitHub Copilot a 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 de solicitação para sugerir atualizações para seções específicas do seu projeto depois de criar o documento ou usar outras ferramentas do GitHub Copilot para ajudar nas atualizações.

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

O modo de edição é melhor para fazer alterações em arquivos específicos no projeto. O modo de edição pode ser usado para gerar a documentação do projeto adicionando arquivos de contexto ao chat e, em seguida, criando ou atualizando arquivos de documentação.

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

  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 edição.

  3. Adicione contexto à sessão de chat.

    Os participantes do chat não estão disponíveis no modo de edição, portanto, você não pode especificar @workspace como parte do prompt. No entanto, você pode adicionar contexto à sessão de chat usando #codebase e arrastando e soltando arquivos ou pastas da exibição EXPLORER do Visual Studio Code para o modo de exibição chat. Use o Visual Studio Code para abrir arquivos externos, como arquivos markdown que contêm diretrizes de colaborador e, em seguida, use o botão Adicionar Contexto para adicioná-los ao contexto de chat.

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

    Por exemplo: "Preciso criar um arquivo README que possa ser usado para o repositório GitHub. O arquivo deve ser formatado como markdown. Crie um arquivo README.md na pasta do workspace raiz. O arquivo README precisa incluir as seguintes seções: Título do Projeto, Descrição, Sumário, Instalação, Uso, Recursos, Configuração e Licença.".

  5. Examine o arquivo de README.md criado usando o modo de edição e salve ou descarte o arquivo.

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

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 processo a seguir para gerar a documentação do projeto, como README.md arquivo, usando o modo de edição:

  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. Arquivos externos podem ser abertos no Visual Studio Code e, em seguida, adicionados ao contexto de chat usando o botão Adicionar 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

O 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. O modo de exibição chat pode ser usado para gerar a documentação do projeto em três modos diferentes: Perguntar, Editar e Agente. 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 de pergunta é melhor para fazer perguntas sobre sua base de código ou conceitos de tecnologia. O modo de edição é melhor para fazer alterações em arquivos específicos no projeto. O modo de agente é melhor para gerar a documentação do projeto que requer uma compreensão mais detalhada do projeto.