Generación de documentación del proyecto mediante GitHub Copilot

  • 6 minutos

La documentación del proyecto describe el propósito, los objetivos y los requisitos de un proyecto. Para crear documentación del proyecto, debe comprender la estructura del proyecto, sus componentes y cómo interactúan entre sí los componentes.

La vista Chat de GitHub Copilot es una herramienta ideal para generar documentación del proyecto, ya que puede analizar toda la estructura del proyecto y proporcionar información general de alto nivel del proyecto. La vista Chat también se puede usar para generar tipos específicos de documentación, como archivos LÉAME, referencias de API y otros documentos relacionados con el proyecto.

Puede usar cada uno de los modos de vista chat (Preguntar, Editar o Agente) para generar documentación del proyecto. Cada modo tiene sus propias fortalezas y debilidades. Las especificaciones del proyecto y otras restricciones afectan al modo que se debe usar.

Importante

Cuando se usa la vista Chat en modo de agente, GitHub Copilot puede realizar varias solicitudes Premium para completar una sola tarea. Las solicitudes Premium se pueden usar mediante avisos iniciados por el usuario y acciones de seguimiento que Copilot realiza en su nombre. El total de solicitudes premium usadas depende de la complejidad de la tarea, del número de pasos implicados y del modelo seleccionado.

Establecimiento de requisitos de documentación del proyecto

Los tipos de documentación y los requisitos de contenido dependen del proyecto, los consumidores previstos y los estándares adoptados por la organización.

Por ejemplo, el README.md podría incluir las secciones siguientes:

  • Título del proyecto: el nombre del proyecto.
  • Descripción: una breve introducción a lo que hace el proyecto y por qué existe.
  • Tabla de contenido: opcional, pero útil para lecturas más largas.
  • Instalación: instrucciones sobre cómo instalar y configurar el proyecto.
  • Uso: ejemplos de cómo usar el proyecto, incluidos fragmentos de código o capturas de pantalla.
  • Características: lista de características o funcionalidades clave.
  • Configuración: detalles sobre las opciones de configuración o las variables de entorno.
  • Contribución: directrices para contribuir al proyecto.
  • Licencia: todas las licencias usadas por el proyecto distribuido.
  • Créditos y confirmaciones: reconocimiento de colaboradores, bibliotecas o recursos usados.
  • Contacto: Cómo ponerse en contacto con los mantenedores o el equipo del proyecto.
  • Registro de cambios: un historial de cambios y actualizaciones (a veces vinculado a un archivo independiente).

El chat de Copilot de GitHub puede ayudarle a generar documentación del proyecto que satisfaga las necesidades específicas del proyecto y sus partes interesadas.

Uso del modo ask para generar documentación del proyecto

El modo ask se puede usar para analizar un área de trabajo y, a continuación, generar documentación.

Utiliza el siguiente proceso para generar documentación del proyecto mediante el modo preguntar.

  1. Identifique los requisitos de documentación y los recursos auxiliares.

    • Identifique los requisitos de documentación del proyecto. Identifique los tipos de documentación y las secciones de documento necesarias.

    • Identifique los recursos necesarios para generar la documentación. El área de trabajo de código podría ser el único recurso necesario. Sin embargo, es posible que tenga que agregar contexto al chat para secciones como "Contribución", "Créditos" y "Contacto".

  2. Abra la vista Chat e inicie una nueva sesión de chat con el modo preguntar.

  3. Agregue contexto a la sesión de chat.

    • Puede agregar contexto a la sesión de chat arrastrando y colocando archivos de la vista EXPLORER de Visual Studio Code en la vista Chat. También puede usar el botón Agregar contexto .
    • Puede abrir archivos externos en el editor de código para incluir recursos que no forman parte del área de trabajo y usarlos para proporcionar más contexto. Por ejemplo, puede abrir archivos markdown que contengan directrices de colaborador o información de contacto y, a continuación, usar el botón Agregar contexto para agregarlos al contexto de la vista chat.

  4. Escriba una serie de indicaciones que exploren sus requisitos de documentación.

    Puede usar el modo de solicitud para analizar el área de trabajo y crear un historial de sesiones de chat que admita los requisitos de documentación. Describir sus objetivos puede ayudar a establecer el contexto de la sesión de chat. Formular preguntas que aborden sus requisitos ayuda a GitHub Copilot a identificar la información necesaria para generar la documentación.

    Actualice el contexto agregado según sea necesario.

  5. Escriba un mensaje que solicite documentación de proyecto sugerida, enumerando las secciones necesarias que identificó en el primer paso.

    Por ejemplo: "@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 la documentación del proyecto sugerido y afina los resultados mediante nuevos avisos si es necesario.

  7. Mueva la documentación del proyecto sugerido a un archivo de documentación del proyecto.

    Por ejemplo, cree un archivo README.md en la raíz del área de trabajo e inserte el contenido sugerido en el archivo.

    Puede usar el modo de solicitud para sugerir actualizaciones para secciones específicas del proyecto después de crear el documento o usar otras herramientas de GitHub Copilot para ayudar con las actualizaciones.

Uso del modo de edición para generar documentación del proyecto

El modo de edición es mejor para realizar cambios en archivos específicos del proyecto. El modo de edición se puede usar para generar documentación del proyecto agregando archivos de contexto al chat y, a continuación, creando o actualizando archivos de documentación.

Use el siguiente proceso para generar documentación del proyecto, como README.md archivo, mediante el modo de edición:

  1. Identifique los requisitos de documentación y los recursos auxiliares.

  2. Abra la vista Chat e inicie una nueva sesión de chat con el modo de edición.

  3. Agregue contexto a la sesión de chat.

    Los participantes del chat no están disponibles en modo de edición, por lo que no se puede especificar @workspace como parte del mensaje. Sin embargo, puede agregar contexto a la sesión de chat mediante #codebase y arrastrando y colocando archivos o carpetas desde la vista EXPLORER de Visual Studio Code en la vista Chat. Use Visual Studio Code para abrir archivos externos, archivos markdown que contienen directrices de colaborador y, a continuación, use el botón Agregar contexto para agregarlos al contexto de chat.

  4. Introduzca una indicación para crear la documentación del proyecto deseado.

    Por ejemplo: "Necesito crear un archivo LÉAME que se pueda usar para el repositorio de GitHub. El archivo debe tener el formato markdown. Cree un archivo README.md en la carpeta del área de trabajo raíz. El archivo LÉAME debe incluir las secciones siguientes: Título del proyecto, Descripción, Tabla de contenido, Instalación, Uso, Características, Configuración y Licencia".

  5. Revise el archivo README.md creado con el modo de edición y, a continuación, guarde o descarte el archivo.

    Puede actualizar el archivo mediante avisos para corregir o mejorar secciones específicas si es necesario.

Uso del modo de agente para generar documentación del proyecto

El modo de agente es mejor para generar documentación del proyecto que requiere una comprensión detallada del proyecto. El modo de agente analiza toda la estructura del proyecto antes de generar la documentación del proyecto. Al recopilar información de varios archivos y carpetas, el modo de agente puede describir relaciones complejas e incluir vínculos entre documentos.

Use el siguiente proceso para generar documentación del proyecto, como README.md archivo, mediante el modo de edición:

  1. Identifique los requisitos de documentación y los recursos auxiliares.

  2. Abra la vista Chat e inicie una nueva sesión de chat con el modo de agente.

  3. Agregue contexto a la sesión de chat.

    Los participantes del chat no están disponibles en modo de agente, por lo que no se puede especificar @workspace como parte del mensaje. Sin embargo, puede agregar contexto a la sesión de chat mediante #codebase y agregando archivos y carpetas del área de trabajo al contexto de chat. Los archivos externos se pueden abrir en Visual Studio Code y, a continuación, agregarlos al contexto de chat mediante el botón Agregar contexto .

  4. Introduzca una indicación para crear la documentación del proyecto deseado.

    Por ejemplo: "Generar una colección de archivos de documentación del proyecto. Cree o actualice el archivo README.md del área de trabajo para este repositorio. Cree o actualice el archivo UsageExamples.md. Cree o actualice el archivo ChangeLog.md. Incluya vínculos entre los archivos de documentación, referencie las clases y los métodos, y garantice la coherencia en los documentos.

  5. Revise los archivos de documento y, a continuación, guarde o descarte las actualizaciones.

    Actualice el archivo mediante avisos para corregir o mejorar secciones específicas si es necesario.

Funcionalidades del modo agente

Hay varias tareas de documentación en las que el modo de agente es la mejor opción.

  1. Generación de documentación multiarchivo y entre archivos.

    • El modo de agente puede analizar toda la estructura del proyecto, recopilar información de varios archivos y carpetas, y generar documentación que vincule y resuma el contenido en el código base. Por ejemplo, la generación de una referencia completa de la API o un archivo README que describa todos los componentes principales.

  2. Análisis y resumen automatizados del proyecto.

    • El modo de agente puede realizar tareas como resumir la arquitectura, identificar las clases o servicios principales y generar diagramas o tablas que requieren comprender las relaciones entre archivos y componentes.

  3. Generación de contenido dinámico (por ejemplo, ejemplos de uso, tablas de clases)

    • El modo de agente puede examinar el proyecto para generar ejemplos de uso, tablas de responsabilidad de clase o listas de API públicas.

  4. Tareas de documentación por lotes.

    • El modo de agente puede ejecutar una secuencia de tareas de documentación (por ejemplo, actualizar LÉAME, crear CONTRIBUTING.md, generar documentos de API, actualizar registro de cambios) en un flujo de trabajo.

  5. Vinculación inteligente y navegación.

    • El modo de agente puede crear vínculos entre archivos de documentación, clases y métodos de referencia cruzada y garantizar la coherencia entre documentos.

El modo de agente es ideal para tareas de documentación que abarcan todo el proyecto, con múltiples archivos y conciencia del contexto, que requieren análisis, síntesis y coordinación.

Resumen

GitHub Copilot puede ayudarle a generar documentación del proyecto que satisfaga las necesidades específicas del proyecto y sus partes interesadas. La vista Chat se puede usar para generar documentación del proyecto en tres modos diferentes: Preguntar, Editar y Agente. Cada modo tiene sus propias fortalezas y debilidades, y el mejor modo de uso depende de la tarea específica a mano. El modo de preguntas es mejor para formular preguntas sobre los conceptos de código base o tecnología. El modo de edición es mejor para realizar cambios en archivos específicos del proyecto. El modo de agente es mejor para generar documentación del proyecto que requiere una comprensión más detallada del proyecto.