Proyecto copiloto de rendimiento

En esta página, se incluyen los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.

Resumen del proyecto

Organización de código abierto:
Copiloto de rendimiento
Escritor técnico:
arzoo14
Nombre del proyecto:
Convierte el contenido de las áreas del proyecto del libro a los formatos readthedocs y reStructuredText, junto con el objetivo adicional de mejorar los diagramas.
Duración del proyecto:
Duración estándar (3 meses)

Project description

RESUMEN:

Un sitio web de la comunidad desempeña un papel fundamental en una organización de código abierto porque difunde la idea de las ofertas que proporciona la comunidad, sus valiosas contribuciones, sus habilidades, la documentación, los instructivos, etc. Por lo tanto, mi proyecto apuntará a aumentar la usabilidad y facilidad de todos los colaboradores de código abierto mediante la transferencia y actualización del contenido de las áreas del proyecto del libro, es decir, el contenido de docbook, la documentación de la API de REST y el formato de R Markdown moderno. Este proyecto también beneficiará a los colaboradores de la comunidad, ya que les permitirá cambiar y extender este contenido con mayor facilidad. Además, como objetivo adicional, se mejorarán los diagramas de la documentación para darles un aspecto más profesional.

PROPUESTA:

  1. DESCRIPCIÓN GENERAL: Actualmente, la documentación de Performance Co-Pilot existe en varios formatos diferentes. Entre estos se incluyen libros para PCP en formato docbook, API de REST en formato de página manual y guías pbench en formato Markdown. Por lo tanto, el grupo de encargados actual de mantenimiento de la organización identificó que necesita una solución que no requiera mantenimiento tanto como sea posible, y que permita que la comunidad de desarrolladores se enfoque por completo en mantener su contenido de forma ágil y sencilla. Por lo tanto, según las necesidades actuales de la organización, implementaré los siguientes objetivos durante esta temporada de documentos de Google:

    1. Convertir el contenido de docbook al formato reStructuredText y alojarlo en el sitio de readthedocs.
    2. Convierte la documentación de la API de REST de la página de manual a un formato fácil de usar para los desarrolladores, es decir, al formato reStructuredText, y alójala en el sitio de readthedocs.
    3. Convertir el contenido de pbench MarkDown al formato reStructuredText y alojarlo en el sitio readthedocs.
    4. Los objetivos adicionales serían mejorar los diagramas presentes en la documentación.

  2. IMPLEMENTACIÓN: Actualmente, la documentación de Performance Co-Pilot no está presente en un formato específico. Cada vez que se debe cambiar el contenido de la documentación, un conjunto restringido de usuarios debe hacerlo. No es tan fácil para los miembros activos de la comunidad cambiar y extender el contenido de la documentación.

Permitiré que la organización supere estas limitaciones durante esta GSoD con la ayuda del formato reStructuredText, Read the Docs (RTD) y Sphinx.

Read the Docs (RTD) simplifica la documentación de software automatizando la compilación, el control de versiones y el alojamiento de nuestros documentos. Es una plataforma de hosting para la documentación generada por Sphinx. Aprovecha la potencia de Sphinx y agrega control de versiones, búsqueda de texto completo y otras funciones útiles. Extrae archivos de código y documentos de Git, Mercurial o Subversion y, luego, compila y aloja nuestra documentación. Usaremos GitHub en nuestro proyecto, ya que es el sistema más usado para acceder al código.

Para comenzar, crearemos una cuenta de Read the Docs y vincularemos la cuenta de GitHub. Luego, seleccionaremos el repositorio de GitHub para el que queremos compilar la documentación, y ahí es cuando sucede la magia.

Read the Docs hará lo siguiente: - Clonará nuestro repositorio. - Compila versiones HTML, PDF y ePub de nuestra documentación desde nuestra rama principal. - Indexar nuestra documentación para permitir la búsqueda en el texto completo - Crear objetos Version a partir de cada etiqueta y rama de nuestro repositorio, lo que nos permite alojarlos también de manera opcional. - Activar un webhook en nuestro repositorio para que, cuando enviemos código a cualquier rama, se vuelva a compilar nuestra documentación

Sphinx es un generador de documentación autorizado que tiene muchas funciones excelentes para escribir documentación técnica, como las siguientes: - Genera páginas web, archivos PDF imprimibles, documentos para lectores electrónicos (ePub) y mucho más, todo desde las mismas fuentes. - Podemos usar reStructuredText para escribir documentación. - Un sistema extenso de código y documentación de referencias cruzadas. - Muestras de código resaltadas en la sintaxis. - Un ecosistema dinámico de extensiones propias y de terceros.

Comenzaré por convertir los dos libros de PCP que están presentes en formato docbook al formato rst, luego, convertiré la documentación de la API de REST del formato de página de man al formato rst, luego, convertiré el contenido de Markdown de pbench al formato rst y, al final, alojaré todo esto en el sitio de readthedocs. Los objetivos ambiciosos serían mejorar los diagramas de la documentación.

2.1. Conversión al formato reStructuredText: El primer paso será convertir el contenido de la documentación al formato reStructuredText. Cada capítulo tendrá un archivo rst independiente, que contendrá solo el contenido de ese capítulo. Por ejemplo, la Guía del usuario y del administrador de Copiloto de rendimiento incluye ocho capítulos. Esto significa que habrá ocho archivos rst diferentes que corresponden a esos ocho capítulos. El nombre del archivo rst será el mismo que el del capítulo para evitar confusiones en el futuro. Habrá una lista de figuras, tablas y listas de ejemplos en tres archivos rst diferentes. El primer contenido tendrá un hipervínculo completo de la misma manera en que está presente actualmente. Se usará lo mismo para la documentación de la API de REST y el contenido de pbench. Se cuidarán todos los elementos necesarios, como negrita, cursiva, subrayado, viñetas, tablas, tamaño de fuente, estilo de código, tamaño de imagen, alineación, etcétera, mientras se convierte el contenido en formato rst.

2.2. Integración de la primera con Sphinx:

ReadtheDocs usa Sphinx y reStructuredText (rst) como opciones predeterminadas. Como Sphinx está preinstalado en mi sistema, comenzaré por crear un directorio dentro del proyecto (llamado Documentation of Performance Co-Pilot) para contener la documentación: $ cd /path/to/project $ mkdir docs

Después, ejecuta sphinx-quickstart allí: $ cd docs $ sphinx-quickstart

En esta guía de inicio rápido, se explicará cómo crear la configuración necesaria. En la mayoría de los casos, solo podemos aceptar los valores predeterminados (pero cuando sea necesario, podemos realizar los cambios esenciales en el archivo de configuración). Cuando termine, tendremos un archivo index.rst, un conf.py y algunos otros archivos. En index.rst, agregaré todos los detalles necesarios sobre el copiloto de rendimiento y crearé encabezados para los libros, la documentación de la API de REST y las guías de pbench. Cuando el usuario haga clic en cualquiera de los encabezados, se abrirán todos los materiales de documentación debajo de ese encabezado.

NOTA: El diseño de la página principal se hará de acuerdo con el consentimiento de los mentores y los miembros de la comunidad, y se cambiará según las necesidades y los requisitos.

El archivo index.rst se compilará en index.html en nuestro directorio de salida de documentación (por lo general, _build/html/index.html). Una vez que tengamos la documentación de Sphinx en un repositorio público, podremos comenzar a usar Read the Docs. Para ello, importaremos los documentos.

Cuando agreguemos un archivo .rst en nuestra documentación, correspondientes a ese archivo, se generarán otros tres archivos: uno en la carpeta doctrees con la extensión .doctree, otro en la carpeta HTML con la extensión .html y el tercero en la carpeta html/_sources con la extensión .rst.txt.

  1. ALOJAMIENTO DE LA DOCUMENTACIÓN: El alojamiento de la documentación en Internet consta de dos pasos: 1. Importar la documentación: Como primer paso, conectaré la cuenta de Read The Docs con GitHub y, luego, importaré nuestro proyecto de documentación para compilarlo. 2. Compilación de la documentación: En unos segundos después de completar el proceso de importación, el código se recuperará automáticamente de nuestro repositorio público y se compilará la documentación.

  2. WEBHOOKS: El método principal que usa Read the Docs para detectar cambios en la documentación y las versiones es mediante webhooks. Los webhooks se configuran con nuestro proveedor de repositorios, como GitHub, y se notifica a Read the Docs cada vez que se confirma, se combina o se realiza otro cambio en nuestro repositorio. Cuando recibimos una notificación de webhook, determinamos si el cambio se relaciona con una versión activa de nuestro proyecto y, si es así, se activa una compilación para esa versión.

De esta manera, cualquier persona (administradores, mentores, colaboradores de la comunidad) puede cambiar, extender o mantener la documentación de la comunidad, y no se necesitará un conjunto restringido de usuarios en particular para cuidar de lo que se debe agregar a la documentación o quitar de ella.

  1. TEMAS: Los temas, los diseños y otras funciones de HTML, como la búsqueda, se basarán en las necesidades y los lineamientos de la comunidad. Durante el período de integración en la comunidad, hablaré de todo esto con los miembros de la comunidad.
  1. ESTIRAR OBJETIVO: Para ampliar el objetivo, mejoraré los diagramas presentes en la documentación. Actualmente, los diagramas son principalmente dibujos simples en blanco y negro. Incorporaré más color, sombreado, escala, coherencia y un aspecto más prolijo y profesional a las imágenes.

Para este fin, usaré draw.io (o cualquier otra herramienta con el consentimiento del mentor).

Como prueba de concepto, mejoré uno de los diagramas presentes en la documentación con la ayuda de draw.io. Puedes encontrarla aquí: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

COMPROBAR EL CONCEPTO

Convirtieron una pequeña parte del libro de PCP (formato DocBook) al formato rst y lo alojaron en el sitio de readthedocs. Puedes encontrarlo aquí.

Sitio web: https://pcp-books.readthedocs.io/en/latest/ Code: https://github.com/arzoo14/PCP_Books_Demo

También configuré webhooks en el repositorio de código con la ayuda de estos, los cambios realizados en el repositorio de código se reflejarán en el sitio web.

CRONOGRAMA Y ENTREGABLES

PERÍODO DE UNIÓN COMUNIDAD [Del 17 de agosto al 13 de septiembre de 2020 ]

Aprovecharé este tiempo para familiarizarme con la comunidad, revisar la documentación y hablar sobre muchos temas con los mentores para asegurarme de no tomar malas decisiones al principio del proceso. Durante este período, hablaré sobre los temas, los diseños, los diseños y otras funciones, como la búsqueda, la barra de navegación, etc., con los mentores y los miembros de la comunidad. Durante el período de vinculación de la comunidad, se analizará el nombre del proyecto y si habrá un solo sitio web para alojar los tres temas o tres sitios web diferentes correspondientes a los tres temas.

PERÍODO DE DESARROLLO DE LOS DOCUMENTOS [14 de septiembre al 30 de noviembre de 2020 ]

***Del 14 al 20 de septiembre de 2020 [SEMANA 1] Conversión del contenido de DocBook al formato rst para los primeros cuatro capítulos del libro de la Guía para usuarios y administradores.

***Del 21 de septiembre de 2020 al 27 de septiembre de 2020 [SEMANA 2] Conversión del contenido de DocBook al formato rst para los próximos cuatro capítulos del libro de la Guía para usuarios y administradores.

***Desde el 28 de septiembre de 2020 hasta el 4 de octubre de 2020 [SEMANA 3] Conversión del contenido del libro al primer formato para los cuatro capítulos de la Guía para programadores.

***Del 5 al 11 de octubre de 2020 [SEMANA 4]: Hosting de los dos libros de PCP en el sitio de readthedocs. - Conversión de la documentación de la API de REST de la página de man al formato rst. La página de destino principal se incluirá durante este período. - Escribí en el blog (sobre mi proyecto de GSoD) durante las últimas tres semanas y la semana actual.

***Del 12 al 18 de octubre de 2020 [SEMANA 5] Conversión del índice de series temporales escalables al formato rst. Los índices de series temporales escalables abarcan lo siguiente: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***Del 19 al 25 de octubre de 2020 [SEMANA 6] Conversión del índice de servicios de host de PMAPI al formato rst. El índice de servicios de host de PMAPI abarca lo siguiente: GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch , GET /pmapi/children GET /pmapi/indom, GET /pmapi/profile , GET /pmapi/store , GET /pmapi/derive GET /pmapi/metrics

***Desde el 26 de octubre de 2020 hasta el 1 de noviembre de 2020 [SEMANA 7] - Si queda algo en las últimas semanas, se tratará primero. - Alojamiento de la documentación de la API de REST en el sitio readthedocs. - Blogs (de mi proyecto de GSoD) durante las últimas dos semanas y la semana en curso.

***Del 2 al 8 de noviembre de 2020 [SEMANA 8] Conversión del contenido de Markdown a formato rst para las guías de pbench.

***Desde el 9 de noviembre de 2020 hasta el 15 de noviembre de 2020 [SEMANA 9] - Se continuó con la conversión del contenido en Markdown al primer formato de las guías de Fitbit. - Alojamiento de las guías de pbench en el sitio de readthedocs. - Blogs (de mi proyecto de GSoD) durante la última semana y la semana en curso.

***Del 16 al 22 de noviembre de 2020 [SEMANA 10]: Implementación de la función de búsqueda en la página de índice para buscar cualquier contenido a partir de su nombre en los sitios web. - Inicio de los objetivos adicionales.

***Del 23 al 30 de noviembre de 2020 [SEMANA 11]: mejora de todos los diagramas presentes en la documentación - El blog final (de mi proyecto de GSoD) de la última y de la semana actual. - Comprobar si la base de código cumple con los estándares de programación De lo contrario, cámbialos a los estándares.

PERÍODO DE FINALIZACIÓN DEL PROYECTO [30 de noviembre al 5 de diciembre de 2020 ]

  • Tiempo de inactividad de Pencil Trabajar en el envío final y asegurarme de que todo esté bien
  • Envío de los informes del proyecto, también conocidos como productos finales del trabajo
  • La presentación de las evaluaciones del éxito de los proyectos y la experiencia de trabajo con los mentores.