Projet de co-pilote de performance

Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.

Résumé du projet

Organisation Open Source:
Copilote axé sur les performances
Rédacteur technique:
arzoo14
Nom du projet:
Convertissez le contenu des sections du projet de livre au format readthedocs et reStructuredText, avec l'objectif de développement de l'amélioration des diagrammes.
Durée du projet:
Durée standard (trois mois)

Project description

RÉSUMÉ:

Un site Web communautaire joue un rôle essentiel dans une organisation Open Source, car il diffuse l'idée des offres que la communauté propose, ses précieuses contributions, ses compétences, ses documentations, ses tutoriels, etc. Mon projet vise donc à améliorer l'usabilité et la facilité d'utilisation pour tous les contributeurs Open Source en transférant et en mettant à jour le contenu des sections du projet de livre, c'est-à-dire le contenu de DocBook, la documentation de l'API REST et le contenu Markdown de pbench au format reStructuredText afin qu'il puisse être hébergé sur le site moderne de la communauté readthedocs.io. Ce projet bénéficiera également aux contributeurs de la communauté, qui pourront modifier et étendre plus facilement ce contenu. De plus, dans le but ambitieux, les diagrammes de la documentation vont être améliorés afin de leur donner un aspect plus professionnel.

PROPOSITION:

  1. PRÉSENTATION : La documentation de Performance Co-Pilot existe actuellement dans plusieurs formats différents. Il s'agit notamment des livres PCP au format docbook, de l'API REST au format manuel et des guides pbench au format Markdown. Le groupe de mainteneurs actuel de l'organisation a donc déterminé qu'il avait besoin d'une solution aussi simple à entretenir que possible, qui permette à la communauté de développeurs de se concentrer entièrement sur la maintenance de son contenu de manière simple et efficace. Donc, conformément aux besoins actuels de l'organisation, je vais mettre en œuvre les objectifs suivants lors de cette saison de Google Docs:

    1. Convertir le contenu DocBook au format reStructuredText et l'héberger sur le site readthedocs.
    2. Conversion de la documentation de l'API REST à partir de la page de manuel vers un format adapté aux développeurs, c'est-à-dire le format reStructuredText, et hébergement sur le site readthedocs.
    3. Conversion du contenu Markdown de pbench au format reStructuredText et hébergement sur le site readthedocs.
    4. Les objectifs ambitieux consistent à améliorer les diagrammes de la documentation.

  2. IMPLÉMENTATION : pour le moment, la documentation de Performance Co-Pilot n'est pas disponible dans un format spécifique. Chaque fois que le contenu de la documentation doit être modifié, il doit l'être par un ensemble limité d'utilisateurs. Il n'est pas si facile pour les membres actifs de la communauté de modifier et d'étendre le contenu de la documentation.

Je laisserai l'organisation surmonter ces limites lors de ce GSoD à l'aide du format reStructuredText, de la lecture des documents (RTD) et de Sphinx.

Read the Docs (RTD) simplifie la documentation logicielle en automatisant la compilation, la gestion des versions et l'hébergement de nos documents. Il s'agit d'une plate-forme d'hébergement de la documentation générée par Sphinx. Il exploite la puissance de Sphinx et ajoute un contrôle des versions, une recherche en texte intégral et d'autres fonctionnalités utiles. Il extrait les fichiers de code et de documentation de Git, Mercurial ou Subversion, puis compile et héberge notre documentation. Nous utiliserons GitHub dans notre projet, car il s'agit du système le plus couramment utilisé pour accéder au code.

Pour commencer, nous allons créer un compte Read the Docs et associer le compte GitHub. Nous allons ensuite sélectionner le dépôt GitHub pour lequel nous souhaitons créer la documentation. La magie opère alors.

Lorsque vous lisez les documents : - Cloner notre dépôt - Créer des versions HTML, PDF et ePub de notre documentation à partir de notre branche principale. - Indexer notre documentation pour permettre la recherche dans le texte complet. - Créez des objets Version à partir de chaque balise et branche de notre dépôt, ce qui nous permet de les héberger également. - Activer un webhook sur notre dépôt afin que notre documentation soit recréée lorsque nous transférons du code vers une branche.

Sphinx est un générateur de documentation fiable qui offre de nombreuses fonctionnalités pour rédiger des documents techniques, y compris : - Générer des pages Web, des PDF imprimables, des documents pour les lecteurs électroniques (ePub), etc. à partir des mêmes sources. - Nous pouvons utiliser reStructuredText pour rédiger de la documentation. - Un système étendu de références croisées entre code et documentation. - Exemples de code de syntaxe mis en évidence - Un écosystème dynamique d'extensions propriétaires et tierces.

Je vais commencer par convertir les deux livres PCP au format rst, puis la documentation de l'API REST au format rst, puis le contenu Markdown de pbench au format rst, puis héberger l'ensemble sur le site readthedocs. Les objectifs ambitieux consistent à améliorer les diagrammes de la documentation.

2.1. Conversion au format reStructuredText : la première étape consiste à convertir la documentation au format reStructuredText. Chaque chapitre aura un fichier rst distinct, qui ne contiendra que le contenu de ce chapitre. Par exemple, le manuel de l'administrateur et de l'utilisateur Performance Co-Pilot comprend huit chapitres. Cela signifie qu'il y aura huit fichiers rst différents correspondant à ces huit chapitres. Le nom du fichier rst sera identique à celui du chapitre pour éviter toute confusion à l'avenir. Une liste de figures, de tableaux et d'exemples sera disponible dans trois fichiers rst différents. Le contenu rst sera entièrement mis en lien hypertexte de la même manière qu'il est actuellement présenté. Il en sera de même pour la documentation de l'API REST et le contenu pbench. Tous les éléments nécessaires, tels que le gras, l'italique, le soulignement, les puces, les tableaux, la taille de la police, le style de code, la taille des images, l'alignement, etc., seront pris en charge lors de la conversion du contenu au format rst.

2.2. Intégration de Sphinx:

ReadtheDocs utilise Sphinx et reStructuredText (rst) par défaut. Comme Sphinx est préinstallé dans mon système, je vais commencer par créer un répertoire dans le projet (nommé "Documentation Performance Co-Pilot") pour y placer les documents : $ cd /path/to/project $ mkdir docs

Ensuite, exécutez sphinx-quickstart : $ cd docs $ sphinx-quickstart

Ce guide de démarrage rapide explique comment créer la configuration nécessaire. Dans la plupart des cas, vous pouvez simplement accepter les valeurs par défaut (mais si nécessaire, vous pouvez apporter les modifications essentielles dans le fichier de configuration). À la fin, nous aurons un fichier index.rst, un fichier conf.py et d'autres fichiers. Dans index.rst, je vais ajouter toutes les informations nécessaires sur Performance Co-Pilot et créer des titres pour les livres, la documentation de l'API REST et les guides pbench. Lorsque l'utilisateur clique sur l'un des titres, tous les documents correspondants s'ouvrent.

REMARQUE: La conception de la page d'index sera effectuée selon l'autorisation des mentors et des membres de la communauté, et sera modifiée en fonction des besoins et des exigences.

L'index.rst sera intégré à index.html dans le répertoire de sortie de la documentation (généralement _build/html/index.html). Une fois la documentation Sphinx dans un dépôt public, nous pouvons commencer à utiliser Read the Docs en important nos documents.

Lorsque nous ajouterons un fichier .rst à notre documentation, trois autres fichiers seront générés en conséquence : un dans le dossier "doctrees" avec l'extension .doctree, un dans le dossier "Html" avec l'extension .html et le troisième dans le dossier html/_sources avec l'extension .rst.txt.

  1. HÉBERGEMENT DE LA DOCUMENTATION : l'hébergement de la documentation sur Internet comprend deux étapes : 1. Importer la documentation: dans un premier temps, je vais associer le compte Read The Docs à GitHub et importer notre projet de documentation à compiler. 2. Compilation de la documentation: quelques secondes après la fin du processus d'importation, le code est automatiquement extrait de notre dépôt public et la documentation est compilée.

  2. WEBHOOKS : la méthode principale utilisée par Read the Docs pour détecter les modifications apportées à la documentation et aux versions est l'utilisation de webhooks. Les webhooks sont configurés avec notre fournisseur de dépôt, comme GitHub. À chaque commit, fusion ou autre modification apportée à notre dépôt, Read the Docs en est informé. Lorsque nous recevons une notification de webhook, nous déterminons si le changement est lié à une version active de notre projet. Si c'est le cas, un build est déclenché pour cette version.

De cette manière, n'importe qui (administrateurs, mentors, contributeurs de la communauté) peut modifier, étendre ou gérer la documentation de la communauté, et aucun groupe restreint d'utilisateurs n'est nécessaire pour s'occuper de ce qui doit être ajouté à la documentation ou de ce qui doit être supprimé de la documentation.

  1. THÈMES : les thèmes, les mises en page, les conceptions et les autres fonctionnalités HTML telles que la recherche seront conformes aux besoins et aux consignes de la communauté. Pendant la période de consolidation de la communauté, je discuterai de tout cela avec ses membres.
  1. OBJECTIF ÉTENDU : En tant qu'objectif étendu, je vais améliorer les diagrammes présents dans la documentation. Actuellement, les diagrammes sont principalement des dessins simples en noir et blanc. J'ajouterai plus de couleurs, d'ombres, de mises à l'échelle, de cohérence et un aspect plus soigné / professionnel aux images.

Pour ce faire, j'utiliserai draw.io (ou tout autre outil avec l'autorisation du mentor).

Dans le cadre d'une démonstration de faisabilité, j'ai amélioré l'un des diagrammes de la documentation à l'aide de draw.io. Vous pouvez le consulter ici: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

DÉMONSTRATION DE FAISABILITÉ

J'ai converti une petite partie du livre PCP (format docbook) au format rst et l'ai hébergée sur le site readthedocs. Vous la trouverez ici.

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

J'ai également configuré des webhooks dans le dépôt de code, grâce auxquels les modifications apportées au dépôt de code seront reflétées sur le site Web.

CALENDRIER ET PRODUITS LIVRABLIS

PÉRIODE DE LIEN COMMUNAUTAIRE [17 août - 13 septembre 2020 ]

Je vais passer ce temps à me familiariser avec la communauté, à consulter la documentation et à discuter de nombreux points avec les mentors pour m'assurer qu'aucune mauvaise décision n'est prise au début du processus. Pendant cette période, je discuterai des thèmes, des mises en page, des conceptions, d'autres fonctionnalités telles que la recherche, la barre de navigation, etc. avec les mentors et les membres de la communauté. Le nom du projet et la question de savoir s'il y aura un seul site Web pour héberger les trois sujets ou trois sites Web différents correspondant aux trois sujets seront discutés pendant la période de consolidation de la communauté.

PÉRIODE DE DÉVELOPPEMENT DU DOCUMENT [ 14 septembre - 30 novembre 2020 ]

***Du 14 septembre 2020 au 20 septembre 2020 [SEMAINE 1] Conversion des quatre premiers chapitres du guide de l'utilisateur et de l'administrateur dans le premier format.

***Du 21 septembre 2020 au 27 septembre 2020 [SEMAINE 2] Conversion du contenu du guide au premier format pour les quatre chapitres suivants du guide de l'utilisateur et de l'administrateur.

***Du 28 septembre 2020 au 4 octobre 2020 [SEMAINE 3]Conversion du contenu du document DocBook au format rst pour les quatre chapitres du guide du programmeur.

***Du 5 octobre 2020 au 11 octobre 2020 [SEMAINE 4] - Hébergement des deux livres PCP sur le site readthedocs. - Conversion de la documentation de l'API REST de la page de manuel au format rst. La page de destination principale sera couverte pendant cette période. - Blogging (de mon projet GSoD) au cours des trois dernières semaines et de la semaine en cours.

***Du 12 octobre 2020 au 18 octobre 2020 [SEMAINE 5]Conversion de l'indice de série temporelle évolutive au format rst. L'index de séries temporelles évolutif couvre les éléments suivants : GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***Du 19 octobre 2020 au 25 octobre 2020 [SEMAINE 6]Conversion de l'index des services hôtes PMAPI au format rst. L'index des services hôtes PMAPI couvre les éléments suivants : 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

***Du 26 octobre 2020 au 1er novembre 2020 [SEMAINE 7] - Si des éléments restent dans les dernières semaines, ils seront traités en priorité. - Hébergement de la documentation de l'API REST sur le site readthedocs. - Blogging (de mon projet GSoD) pendant les deux dernières semaines et la semaine en cours.

***Du 2 novembre 2020 au 8 novembre 2020 [SEMAINE 8] Conversion du contenu Markdown au premier format pour les guides pbench.

***Du 9 novembre 2020 au 15 novembre 2020 [SEMAINE 9] - Poursuite de la conversion du contenu Markdown au format rst pour les guides pbench. - Hébergement des guides pbench sur le site readthedocs. - Blogging (de mon projet GSoD) pour la semaine dernière et la semaine en cours.

***Du 16 novembre 2020 au 22 novembre 2020 [SEMAINE 10] - Implémentation de la fonctionnalité de recherche sur la page d'index pour rechercher n'importe quel contenu à partir de son nom sur le ou les sites Web. - Initiation des objectifs ambitieux.

***Du 23 novembre 2020 au 30 novembre 2020 [SEMAINE 11] - Amélioration de tous les diagrammes présents dans la documentation. - Le dernier article de blog (de mon projet GSoD) pour la semaine dernière et la semaine en cours. - Vérifier si le codebase est conforme aux normes de codage. Si ce n'est pas le cas, les mettre en conformité avec les normes.

PÉRIODE DE FINALISATION DU PROJET [30 novembre - 5 décembre 2020 ]

  • Temps d'arrêt du crayon. Travailler sur l'envoi final et s'assurer que tout est correct.
  • Envoi des rapports de projet, également appelés "produits finaux".
  • Envoi des évaluations de la réussite des projets et de l'expérience de travail avec les mentors.