Proyecto copiloto de rendimiento

Esta página contiene 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 de libro a los formatos readthedocs y reStructuredText, junto con el objetivo más amplio de mejorar los diagramas.
Duración del proyecto:
Duración estándar (3 meses)

Project description

RESUMEN:

El sitio web de la comunidad desempeña un papel esencial en una organización de código abierto porque difunde la idea de las ofertas que brinda la comunidad, sus valiosas contribuciones, sus habilidades, su documentación, sus tutoriales, etc. Por lo tanto, mi proyecto tendrá como objetivo 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 de libros, es decir, el contenido de los docbook, la documentación de la API de REST y el contenido de la API de REST alojado en este formato de la comunidad. Este proyecto también beneficiará a los colaboradores de la comunidad, ya que les permitirá cambiar y extender el contenido con mayor facilidad. Además, como objetivo más amplio, 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 del Copiloto de rendimiento existe en varios formatos diferentes. Estos incluyen libros de PCP en formato de docbook, API de REST en formato de página de manual y guías de Pbench en formato Markdown. Por lo tanto, el grupo de encargados de mantenimiento actual de la organización identificó que necesita una solución que no requiera mantenimiento en la mayor medida posible y que permita a la comunidad de desarrolladores enfocarse por completo en mantener su contenido de una manera sencilla y ágil. Por lo tanto, en función de las necesidades actuales de la organización, implementaré los siguientes objetivos durante esta temporada de Google Docs:

    1. Cómo convertir el contenido de un docbook al formato reStructuredText y alojarlo en el sitio readthedocs.
    2. Cómo convertir la documentación de la API de REST de una página de manual a un formato fácil de usar para el desarrollador, es decir, un formato reStructuredText y alojarlo en el sitio readthedocs.
    3. Se convirtió el contenido de MarkDown de Pbench en el formato reStructuredText y se aloja en el sitio readthedocs.
    4. Los objetivos generales serían mejorar los diagramas presentes en la documentación.

  2. IMPLEMENTACIÓN: Actualmente, la documentación del Copiloto de rendimiento no se presenta en un formato específico. Siempre que se deba 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.

Leer los Documentos (RTD) simplifica la documentación del software, ya que automatiza 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 versión, búsqueda en el texto completo y otras funciones útiles. Extrae códigos y archivos de 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 utilizado para acceder al código.

Para comenzar, crearemos una cuenta de lectura de Documentos y vincularemos la cuenta de GitHub. Luego, seleccionaremos el repositorio de GitHub para el que queremos crear documentación. Ahí ocurre la magia.

Leer los documentos hará lo siguiente: - Clonará nuestro repositorio. - Compilar versiones HTML, PDF y ePub de nuestra documentación desde la 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 alojar esos también de forma opcional - Activar un webhook en nuestro repositorio, de modo que cuando enviemos código a cualquier rama, nuestra documentación se vuelva a compilar.

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

Comenzaré con la conversión de los dos libros de PCP que están presentes en formato de docbook al primero, después de la conversión de la documentación de la API de REST del formato de página manual a primer formato, luego la conversión del contenido de PBench Markdown al primer formato y, por último, se alojarán todos estos en el sitio readthedocs. Los objetivos más amplios serían mejorar los diagramas de la documentación.

2.1. Conversión a formato reStructuredText: El primer paso será convertir el contenido de la documentación al formato reStructuredText. Cada capítulo tendrá un primer archivo independiente que incluirá únicamente el contenido de ese capítulo. Por ejemplo, la Guía del usuario y del administrador del copiloto de rendimiento incluye ocho capítulos. Significa que habrá ocho primeros archivos diferentes correspondientes a esos ocho capítulos. El nombre del primer archivo será el mismo que el nombre del capítulo para evitar confusiones en el futuro. En tres primeros archivos diferentes, habrá una lista de figuras, tablas y listas de ejemplos. El primer contenido tendrá un hipervínculo de la misma forma en que está presente actualmente. Se usará lo mismo para la documentación de la API de REST y el contenido de Pbench. Todo lo necesario, como negrita, cursiva, subrayado, viñetas, tablas, tamaño de fuente, estilo de código, tamaño de imagen, alineación, etc., se tendrá en cuenta al convertir el contenido al primer formato.

2.2. Integración de Sphinx:

ReadtheDocs usa Sphinx y reStructuredText (primero) como valores predeterminados. Como Sphinx está preinstalado en mi sistema, comenzaré por crear un directorio dentro del proyecto (denominado “Performance Co-Pilot Documentation)” para guardar los siguientes documentos: $ cd /path/to/project $ mkdir docs

Luego, ejecutarás la guía de inicio rápido de Sphinx 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, realizaremos los cambios esenciales en el archivo de configuración). Cuando esté listo, tendremos un index.rst, un conf.py y algunos otros archivos. En index.rst, agregaré todos los detalles necesarios sobre la prueba piloto 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 de índice dependerá del consentimiento de los mentores y de los miembros de la comunidad, y se modificará según las necesidades y los requisitos.

El archivo index.rst se compilará en index.html en el directorio de salida de nuestra documentación (por lo general, _build/html/index.html). Una vez que tengamos la documentación de Sphinx en un repositorio público, podremos empezar a usar la función Leer los documentos importando los documentos.

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

  1. PRESENTACIÓN DE LA DOCUMENTACIÓN: El alojamiento de la documentación en Internet consta de dos pasos: 1. Importación de la documentación: Como primer paso, conectaré la cuenta de lectura de Documentos con GitHub e importaré nuestro proyecto de documentación para compilar. 2. Compilación de la documentación: Pocos segundos después de completar el proceso de importación, se recuperará el código automáticamente de nuestro repositorio público y se creará la documentación.

  2. WEBHOOKS: El método principal que lee los documentos usa para detectar cambios en la documentación y las versiones es mediante el uso de webhooks. Los webhooks se configuran con nuestro proveedor de repositorios, como GitHub, y con cada confirmación, combinación o cambio en nuestro repositorio, la página Leer los documentos recibe una notificación. Cuando recibimos una notificación de webhook, determinamos si el cambio está relacionado con una versión activa de nuestro proyecto; si lo es, 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 específico de usuarios restringido para ocuparse de lo que se debe agregar a la documentación o lo que debe eliminarse de la documentación.

  1. TEMAS: Los temas, diseños, diseños y otras funciones de HTML, como la búsqueda, se aplicarán de acuerdo con las necesidades y los lineamientos de la comunidad. En el período de vinculación con la comunidad, debatiré todo esto con los miembros de la comunidad.
  1. ESTIRAR OBJETIVO: Como un objetivo más amplio, mejoraré los diagramas presentes en la documentación. Actualmente, los diagramas son, en su mayoría, dibujos sencillos en blanco y negro. Incorporaré más color, sombreado, escala, coherencia y un aspecto generalmente más prolijo o profesional a las imágenes.

Para ello, 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

PRUEBA DE CONCEPTO

Convertí una pequeña parte del libro de PCP (formato de docbook) al primer formato y lo almacené en el sitio readthedocs. Encuéntralo aquí.

Sitio web: https://pcp-books.readthedocs.io/en/latest/ Código: 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 ENTREGAS

PERÍODO DE VÍNCULO DE LA COMUNIDAD [del 17 de agosto al 13 de septiembre de 2020 ]

Dedicaré este tiempo a familiarizarme con la comunidad, revisar la documentación y debatir muchas cosas con los mentores para asegurarme de que no se tomen malas decisiones al principio del proceso. Analizaré 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 este período. La decisión sobre el nombre del proyecto y si habrá un único sitio web para alojar los tres temas o tres sitios web diferentes correspondientes a los tres temas se tratarán durante el período de vinculación con la comunidad.

PERÍODO DE DESARROLLO DEL DOCUMENTO [ Del 14 de septiembre al 30 de noviembre de 2020 ]

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

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

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

***Del 5 de octubre de 2020 al 11 de octubre de 2020 [SEMANA 4] - Hosting de los libros del PCP en el sitio de readthedocs. - Conversión de la documentación de la API de REST de la página del manual al primer formato. La página de destino principal se abarcará durante este período. - Publicar blogs (de mi proyecto de GSoD) durante las últimas tres semanas y la semana en curso

***Del 12 al 18 de octubre de 2020 [SEMANA 5] Conversión del índice de series temporales escalable al primer formato. El índice de serie temporal escalable abarca 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 la PMAPI al primer formato. 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

***Del 26 de octubre de 2020 al 1 de noviembre de 2020 [SEMANA 7] - Si queda algo en las últimas semanas, hablaremos primero. - Alojamiento de documentación de la API de REST en el sitio readthedocs. - La publicación de blogs (de mi proyecto de GSoD) durante las últimas dos semanas y la semana actual.

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

***Del 9 al 15 de noviembre de 2020 [SEMANA 9] - Continuamos con la conversión del contenido de Markdown al primer formato para las guías de Pbench. - Alojamiento de las guías de Pbench en el sitio readthedocs. - Blogs (de mi proyecto de GSoD) durante la última semana y la actual.

***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 de su nombre en los sitios web. - Inicio de objetivos extendidos.

***Del 23 de noviembre al 30 de noviembre de 2020 [SEMANA 11] - Mejoras de todos los diagramas presentes en la documentación. - El blog final (de mi proyecto de GSoD) de la última semana y la actual. - Comprobar si la base de código cumple o no con los estándares de codificación Si no es así, cámbialas a los estándares.

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

  • Tiempo de inactividad del lápiz. Trabajar en el envío final y asegurarse de que todo está bien.
  • Presentación de los informes del proyecto, también conocidos como productos de trabajo final.
  • presentación de evaluaciones sobre el éxito de los proyectos y la experiencia laboral con los mentores.