Projet de co-pilote de performance

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

Résumé du projet

Organisation Open Source:
Co-pilote de performance
Rédacteur technique:
arzoo14
Nom du projet:
Convertir le contenu des zones d'un projet de livre au format readthedocs et reStructuredText, avec l'objectif global d'améliorer les diagrammes.
Durée du projet:
Durée standard (3 mois)

Project description

EXTRAIT:

Un site Web de la communauté joue un rôle essentiel dans une organisation open source, car il propage l’idée des offres fournies par la communauté, leurs précieuses contributions, leurs compétences, leurs documentations, leurs tutoriels, etc. Mon projet vise à améliorer la facilité d’utilisation et la facilité d’utilisation pour tous les contributeurs Open Source en transférant et en mettant à jour le contenu des zones de projet du livre, c’est-à-dire le contenu des documents, la documentation de l’API REST et le contenu structuré de la communauté. Ce projet sera également bénéfique pour les contributeurs de la communauté, car il leur permettra de modifier et d'étendre plus facilement ce contenu. En outre, dans un objectif ambitieux, les diagrammes de la documentation seront améliorés pour leur donner un aspect plus professionnel.

PROPOSITION:

  1. PRÉSENTATION : La documentation du co-pilote sur les performances existe actuellement dans plusieurs formats. Cela inclut les ouvrages PCP au format docbook, l'API REST au format page de manuel et les guides pbench au format Markdown. Le groupe de maintenance actuel de l'organisation a donc identifié qu'il avait besoin d'une solution qui demande le moins de maintenance possible, et qui permette à la communauté des développeurs de se consacrer entièrement à la maintenance de son contenu de manière simple et rationalisée. Donc, conformément aux besoins actuels de l'organisation, je vais mettre en œuvre les objectifs suivants au cours de cette saison de Google Docs:

    1. Conversion du contenu du livret de documents au format reStructuredText et hébergement sur le site readthedocs.
    2. Conversion de la documentation de l'API REST d'une page de manuel à un format adapté aux développeurs, c'est-à-dire au format reStructuredText, et hébergement de celle-ci sur le site readthedocs.
    3. Conversion du contenu pbench MarkDown au format reStructuredText et hébergement sur le site readthedocs.
    4. Des objectifs ambitieux consisteraient à améliorer les diagrammes présents dans la documentation.

  2. IMPLÉMENTATION : Actuellement, la documentation du co-pilote sur les performances n'est pas présente dans un format spécifique. Chaque fois que le contenu d'une documentation doit être modifié, le contenu doit l'être par un nombre restreint 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 vais laisser l'organisation surmonter ces limites lors de ce GSoD grâce au format reStructuredText, à la lecture des documents (RTD) et au Sphinx.

Consultez ces documents pour simplifier la documentation logicielle en automatisant la création, la gestion des versions et l'hébergement de nos documents. Il s'agit d'une plate-forme d'hébergement pour la documentation générée par Sphinx. Il exploite la puissance de Sphinx et ajoute le contrôle des versions, la recherche en texte intégral et d'autres fonctionnalités utiles. Il extrait les fichiers de code et de document de Git, Mercurial ou Subversion, puis crée 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 de lecture des documents et l'associer au compte GitHub. Ensuite, sélectionnons le dépôt GitHub pour lequel nous souhaitons créer de la documentation. La magie opère alors.

Lisez le document qui : - Cloner notre dépôt - Créez des versions HTML, PDF et ePub de notre documentation à partir de notre branche principale. - Indexez notre documentation pour permettre la recherche en texte intégral. - Créer des objets Version à partir de chaque tag et branche dans notre dépôt, ce qui nous permettra de les héberger aussi éventuellement. - Activer un webhook dans notre dépôt, afin que notre documentation soit recréée lorsque nous transférons du code vers n'importe quelle branche

Sphinx est un générateur de documentation faisant autorité. Il offre de nombreuses fonctionnalités très utiles pour rédiger des documents techniques, y compris : - Générez des pages Web, des PDF imprimables, des documents pour liseuses (ePub) et bien plus encore, le tout à partir des mêmes sources. - Nous pouvons utiliser reStructuredText pour écrire la documentation. - Un système étendu de recoupement du code et de la documentation. - Exemples de code en surbrillance de la syntaxe. – Un écosystème dynamique d'extensions propriétaires et tierces.

Je vais commencer par convertir les deux ouvrages PCP présents au format docbook au premier format, puis procéder à la conversion de la documentation de l'API REST du format page de manuel au format précédent. Ensuite, la conversion du contenu pbench markdown au premier format, et à la fin, l'hébergement de tous ces éléments sur le site readthedocs. Les objectifs étendus seraient d'améliorer les diagrammes de la documentation.

2.1. Conversion au format reStructuredText : la première étape consiste à convertir le contenu de la documentation au format reStructuredText. Chaque chapitre sera associé à un premier fichier distinct, contenant uniquement le contenu de ce chapitre. Par exemple, le livret du co-pilote de l'utilisateur et de l'administrateur comporte huit chapitres. Cela signifie qu'il y aura huit premiers fichiers différents correspondant à ces huit chapitres. Pour éviter toute confusion à l'avenir, le nom du premier fichier sera identique à celui du chapitre. Une liste de figures, de tableaux et de listes d'exemples se trouve dans trois premiers fichiers différents. Le premier contenu sera étroitement lié à des liens hypertexte, de la même manière qu'il est actuellement présent. La même chose sera utilisée pour la documentation de l'API REST et pour le contenu pbench. Tous les éléments nécessaires (gras, italique, souligné, puces, tableaux, taille de police, style de code, taille d'image, alignement, etc.) seront pris en compte lors de la conversion du contenu au premier format.

2.2. Intégration de la première dans 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 du co-pilote Performance") pour contenir les documents : $ cd /path/to/project $ mkdir docs

Ensuite, j'exécute sphinx-quickstart : $ cd docs $ sphinx-quickstart

Ce guide de démarrage rapide vous explique comment créer la configuration nécessaire. Dans la plupart des cas, nous pouvons simplement accepter les valeurs par défaut. Toutefois, si nécessaire, nous pouvons apporter les modifications essentielles dans le fichier de configuration. Une fois l'opération terminée, nous disposons d'un fichier index.rst, d'un fichier conf.py et d'autres fichiers. Dans index.rst, je vais ajouter toutes les informations nécessaires sur le co-pilote Performance et créer les en-têtes pour les livres, la documentation sur l'API REST et les guides pbench. Lorsque l'utilisateur cliquera sur l'un des titres, il ouvrira tous les supports de documentation sous ce titre.

REMARQUE: La conception de la page d'index sera conforme au consentement des mentors et des membres de la communauté, et sera modifiée en fonction des besoins et des exigences.

Le fichier index.rst sera intégré au fichier index.html dans le répertoire de sortie de notre documentation (généralement _build/html/index.html). Une fois que nous disposons de la documentation Sphinx dans un référentiel public, nous pouvons commencer à utiliser la fonctionnalité Lire la documentation en important nos documents.

Lorsque nous ajoutons un fichier .rst dans notre documentation, correspondant à ce fichier, trois autres fichiers sont générés : le premier dans le dossier doctrees avec l'extension .doctree, le deuxième 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 LA DOCUMENTATION : L'hébergement de la documentation sur Internet s'effectue en deux étapes : 1. Importation de la documentation: dans un premier temps, je vais connecter le compte Read The Docs à GitHub et importer notre projet de documentation pour le créer. 2. Création 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 créée.

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

De cette façon, n'importe quel utilisateur (administrateurs, mentors, contributeurs de la communauté) peut modifier, étendre ou maintenir la documentation de la communauté, et aucun groupe d'utilisateurs restreint ne sera 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, mises en page, conceptions et autres fonctionnalités HTML comme la recherche seront conformes aux besoins et aux directives de la communauté. Pendant la période de cohésion de la communauté, je vais en discuter avec les membres de la communauté.
  1. OBJECTIF ÉTIREMENT : En tant qu'objectif ambitieux, je vais améliorer les diagrammes présents dans la documentation. Actuellement, les diagrammes sont principalement de simples dessins en noir et blanc. Je vais ajouter plus de couleurs, d'ombrage, de mise à l'échelle, de cohérence et d'aspect généralement plus net / plus professionnel aux images.

À cette fin, j'utiliserai draw.io (ou tout autre outil avec le consentement du mentor).

En guise de démonstration de faisabilité, j'ai amélioré l'un des diagrammes présents dans la documentation à l'aide de draw.io. Pour en savoir plus: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

PREUVE DU CONCEPT

J'ai converti une petite partie du PCP (format docbook) au premier format et je l'ai hébergé sur le site readthedocs. Vous le 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. Les modifications apportées au dépôt de code seront ainsi répercutées sur le site Web.

DÉLAI ET LIVRAISON

PÉRIODE D'OBLIGATION POUR LA COMMUNAUTÉ [du 17 août au 13 septembre 2020 ]

Je vais passer ce temps à me familiariser avec la communauté, à parcourir la documentation et à discuter de nombreux points avec les mentors afin de m'assurer qu'aucune mauvaise décision n'est prise dès le début du processus. Je discuterai des thèmes, des mises en page, des conceptions et d'autres fonctionnalités telles que la recherche, la barre de navigation, etc. avec les mentors et les membres de la communauté au cours de cette période. La décision concernant le nom du projet et le fait qu'il y ait un seul site Web pour héberger les trois sujets ou trois sites Web différents correspondant à ces trois sujets seront abordés au cours de la période de cohésion communautaire.

PÉRIODE DE DÉVELOPPEMENT DES DOCUMENTS [14 septembre - 30 novembre 2020 ]

***Du 14 septembre 2020 au 20 septembre 2020 [SEMAINE 1] Conversion du contenu du manuel au premier format pour les quatre premiers chapitres du guide des utilisateurs et des administrateurs.

***Du 21 septembre 2020 au 27 septembre 2020 [SEMAINE 2] Conversion du contenu du manuel au premier format pour les quatre chapitres suivants du guide des utilisateurs et des administrateurs.

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

***Du 5 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 premier format. La page de destination principale est couverte au cours de cette période. - Création de blogs (dans le cadre 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'index de séries temporelles évolutif au premier format. L'index de série temporelle é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 premier format. 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] - S'il reste quelque chose au cours des dernières semaines, il sera pris en charge en premier. - Hébergement de la documentation de l'API REST sur le site readthedocs. - Création de blogs (dans le cadre de mon projet GSoD) au cours des deux dernières semaines et de 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 au 15 novembre 2020 [SEMAINE 9] - Suite de la conversion du contenu Markdown au premier format pour les guides Pbench. - Hébergement des guides Pbench sur le site readthedocs. - Les blogs (dans le cadre de mon projet GSoD) au cours de la semaine précédente et de la semaine en cours.

***Du 16 novembre 2020 au 22 novembre 2020 [SEMAINE 10] – Mise en œuvre de la fonctionnalité de recherche sur la page d'index pour rechercher n'importe quel contenu provenant de son nom sur le ou les sites Web. – La mise en place d'objectifs plus ambitieux

***Du 23 novembre 2020 au 30 novembre 2020 [SEMAINE 11] - Amélioration de tous les diagrammes présents dans la documentation. - La dernière publication de mon blog (de mon projet GSoD) pour la semaine dernière et la semaine en cours. - Vérification que le codebase est conforme aux normes de codage ou non. Si ce n'est pas le cas, remplacez-les par les normes.

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

  • Crayon en pause. Nous travaillons sur la soumission finale et s'assure que tout est correct.
  • Soumission des rapports de projet, également appelés produits de travail finaux.
  • Soumission des évaluations de la réussite des projets et de l'expérience professionnelle avec les mentors.