Generación de documentación del proyecto mediante GitHub Copilot
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, Agente o Plan) 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
Al usar la vista Chat en el modo de agente, cada mensaje que escriba cuenta como una solicitud Premium, multiplicada por el multiplicador del modelo. GitHub Copilot puede realizar varias acciones de seguimiento para completar la tarea, pero estas acciones de seguimiento no cuentan para el uso de la solicitud Premium. Solo se facturan las indicaciones que escriba. El total de solicitudes premium usadas depende del número de mensajes que escriba 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).
GitHub Copilot Chat puede ayudarle a generar documentación del proyecto que satisfaga las necesidades específicas del proyecto y sus partes interesadas.
Uso del modo Preguntar al agente para generar documentación del proyecto
El modo Ask agent se puede usar para analizar un área de trabajo y, a continuación, generar documentación.
Use el siguiente proceso para generar documentación del proyecto mediante el modo Preguntar al agente:
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".
Abra la vista Chat e inicie una nueva sesión de chat con el modo Solicitar agente.
Agregue contexto a la sesión de chat.
- Puede agregar contexto a la sesión de chat arrastrando y soltando archivos desde la vista "EXPLORER" de Visual Studio Code a la vista "Chat". También puede usar el botón Adjuntar contexto (icono de paperclip).
- 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 Asociar contexto para agregarlos al contexto de la vista chat.
Escriba una serie de indicaciones que exploren sus requisitos de documentación.
Puede usar el modo Preguntar al agente 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 identificar la información necesaria para generar la documentación.
Actualice el contexto agregado según sea necesario.
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."Revise la documentación del proyecto sugerido y afina los resultados mediante nuevos avisos si es necesario.
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 Preguntar al agente 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 plan para generar documentación del proyecto
El modo de plan es mejor para crear un plan de implementación detallado antes de generar documentación del proyecto. El modo Plan analiza el código base, identifica los requisitos de documentación y genera un plan paso a paso. Una vez aprobado el plan, puede entregarlo al modo de agente para su ejecución.
Use el siguiente proceso para generar documentación del proyecto, como un archivo README.md, mediante el modo Plan:
Identifique los requisitos de documentación y los recursos auxiliares.
Abra la vista Chat e inicie una nueva sesión de chat con el modo Plan.
Escriba un mensaje que describa la tarea de documentación.
Por ejemplo: "Necesito crear un archivo LÉAME y documentación auxiliar para este proyecto. El archivo Léame debe incluir: Título del proyecto, Descripción, Tabla de contenidos, Instalación, Uso del proyecto, Características, Configuración y Licencia.
Revise el plan de implementación.
Después de unos instantes, el agente de planificación genera un plan en la vista de Chat. El plan proporciona un resumen general y un desglose de los pasos, incluidas las preguntas abiertas para la aclaración. Puede iterar varias veces para aclarar los requisitos, ajustar el ámbito o responder preguntas.
Una vez completado el plan, seleccione Iniciar implementación para entregar el plan al modo de agente o seleccione Abrir en el Editor para guardar el plan como un archivo Markdown para su uso posterior.
Al seleccionar Iniciar implementación, GitHub Copilot cambia al modo de agente y comienza a implementar la documentación basada en el plan aprobado. Revise los archivos de documentación generados y acepte o descarte los cambios.
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 agente:
Identifique los requisitos de documentación y los recursos auxiliares.
Abra la vista Chat e inicie una nueva sesión de chat con el modo de agente.
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
@workspacecomo parte del mensaje. Sin embargo, puede agregar contexto a la sesión de chat mediante#codebasey 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 Attach Context.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.
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.
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, generar una referencia de API completa o un archivo Léame que describa todos los componentes principales.
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.
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.
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.
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, Agente y Plan. Cada modo tiene sus propias fortalezas y debilidades, y el mejor modo de uso depende de la tarea específica a mano. El modo del agente de consultas es mejor para formular preguntas sobre su base de código o conceptos tecnológicos. El modo agente es mejor para generar documentación del proyecto que requiere una comprensión detallada del proyecto. El modo Plan es mejor para crear un plan de implementación detallado antes de generar documentación, que luego se puede entregar al modo agente para su ejecución.