Progetto co-pilota per prestazioni

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

Riepilogo del progetto

Organizzazione open source:
Co-pilota prestazionale
Technical writer:
arzoo14
Nome progetto:
Converti i contenuti delle aree dei progetti dei libri in formato readthedocs e reStructuredText insieme all'obiettivo principale di miglioramento dei diagrammi.
Durata del progetto:
Durata standard (3 mesi)

Project description

SINTESI:

Un sito web della community svolge un ruolo essenziale in un'organizzazione open source perché diffonde l'idea delle offerte fornite dalla community, dei loro preziosi contributi, delle loro competenze, della loro documentazione, dei loro tutorial, ecc. Quindi, il mio progetto mira ad aumentare l'usabilità e la facilità per tutti i collaboratori open source trasferendo e aggiornando i contenuti delle aree del progetto di libro, ad esempio i contenuti dei docbook, la documentazione dell'API REST e la lettura dei contenuti della community in formato moderno. Questo progetto andrà anche a vantaggio dei collaboratori della community, consentendo loro di modificare ed estendere questi contenuti più facilmente. Oltre che, come obiettivo principale, i diagrammi nella documentazione saranno migliorati per dargli un aspetto più professionale.

PROPOSTA:

  1. PANORAMICA: la documentazione del co-progetto pilota al momento è disponibile in vari formati. Questi includono libri PCP in formato docbook, API REST in formato manpage e guide pbench in formato markdown. Quindi, l'attuale gruppo di gestori dell'organizzazione ha identificato di aver bisogno di una soluzione il più possibile esente da manutenzione e che permetta alla community di sviluppatori di concentrarsi interamente sulla manutenzione dei propri contenuti in modo semplice e semplice. Quindi, in base alle attuali esigenze dell'organizzazione, implementerò i seguenti obiettivi durante questa stagione di Documenti Google:

    1. Conversione dei contenuti dei docbook nel formato reStructuredText e hosting dei contenuti sul sito di readthedocs.
    2. Conversione della documentazione dell'API REST da una pagina manuale a un formato adatto agli sviluppatori, ovvero il formato reStructuredText e di ospitarla sul sito readthedocs.
    3. Conversione dei contenuti di pbench MarkDown in formato reStructuredText e hosting dei contenuti sul sito di readthedocs.
    4. Gli obiettivi di stretching dovrebbero consentire di migliorare i diagrammi presenti nella documentazione.

  2. IMPLEMENTAZIONE: al momento, la documentazione del co-pilota per le prestazioni non è presente in un formato specifico. Ogni volta che i contenuti della documentazione devono essere modificati, devono essere modificati da un insieme limitato di utenti. Non è facile per i membri attivi della community modificare ed estendere i contenuti della documentazione.

Lascerò che l'organizzazione superi queste limitazioni durante questo GSoD con l'aiuto del formato reStructuredText, di Read the Docs (RTD) e di Sphinx.

La funzionalità Read the Docs (RTD) semplifica la documentazione del software automatizzando la creazione, il controllo delle versioni e l'hosting dei nostri documenti per noi. È una piattaforma di hosting per la documentazione generata da Sphinx. Prende la potenza di Sphinx e aggiunge il controllo della versione, la ricerca a testo intero e altre funzionalità utili. Recupera file di codice e doc da Git, Mercurial o Subversion, quindi crea e ospita la nostra documentazione. Utilizzeremo GitHub nel nostro progetto in quanto è il sistema più usato per accedere al codice.

Per iniziare, creeremo un account Leggi i documenti e collegheremo l'account GitHub. Successivamente, selezioneremo il repository GitHub per cui vogliamo creare la documentazione, e a quel punto avrà luogo la magia.

Leggi i documenti per: - Clonare il nostro repository. - Creare versioni HTML, PDF ed ePub della nostra documentazione dal ramo principale. - Indicizzare la nostra documentazione per consentire la ricerca a testo intero. - Crei oggetti Version da ogni tag e ramo nel nostro repository, in modo da poterci ospitare anche questi, facoltativamente. - Attivi un webhook nel nostro repository in modo che, quando eseguiamo il push del codice su un ramo, la documentazione venga ricreata.

Sphinx è un generatore di documentazione autorevole che offre molte utili funzionalità per la scrittura di documentazione tecnica, tra cui: - Genera pagine web, PDF stampabili, documenti per e-reader (ePub) e altro ancora, il tutto dalle stesse fonti. - Possiamo utilizzare reStructuredText per scrivere documentazione. - Un ampio sistema di controllo incrociato del codice e della documentazione. - Esempi di codice evidenziato dalla sintassi. - Un vivace ecosistema di estensioni proprietarie e di terze parti.

Inizierò con la conversione dei due libri PCP presenti nel formato docbook nel primo formato, dopo la conversione della documentazione dell'API REST dal formato della pagina man al primo formato, poi la conversione dei contenuti di markup di pbench nel primo formato e, alla fine, l'hosting di tutti questi contenuti sul sito readthedocs. Gli obiettivi di stretching sarebbero il miglioramento dei diagrammi nella documentazione.

2.1. Conversione nel formato reStructuredText: Il primo passaggio consiste nel convertire i contenuti della documentazione nel formato reStructuredText. Ogni capitolo avrà un primo file separato che conterrà solo il contenuto di quel capitolo. Ad esempio, la Guida per l'utente e l'amministratore del co-progetto pilota di prestazioni include otto capitoli. Ciò significa che ci saranno otto diversi file di primo livello corrispondenti a questi otto capitoli. Il nome del primo file sarà uguale a quello del capitolo, per evitare confusione in futuro. Un elenco di figure, tabelle ed elenchi di esempi saranno disponibili in tre diversi file di primo livello. I primi contenuti saranno link ipertestuali inclusi nel modo in cui sono presenti. La stessa cosa verrà utilizzata per la documentazione dell'API REST e i contenuti di pbench. Durante la conversione dei contenuti nel primo formato verranno gestiti tutti gli aspetti necessari, come grassetto, corsivo, sottolineato, elenchi puntati, tabelle, dimensioni del carattere, stile del codice, dimensioni delle immagini, allineamento e così via.

2.2. Integrazione iniziale con Sphinx:

ReadtheDocumenti utilizza Sphinx e reStructuredText (rst) come impostazione predefinita. Poiché Sphinx è preinstallato nel mio sistema, inizierò con la creazione di una directory all'interno del progetto (denominata Performance Co-Pilot Documentazione) in cui inserire i documenti: $ cd /path/to/project $ mkdir docs

Eseguiamo quindi l'esecuzione della guida rapida sphinx: $ cd documenti $ sphinx-quickstart

Questa guida rapida ti guiderà nella creazione della configurazione necessaria; nella maggior parte dei casi, possiamo semplicemente accettare i valori predefiniti (ma se necessario, possiamo apportare le modifiche essenziali nel file di configurazione). Al termine, avremo un file index.rst, conf.py e alcuni altri file. In index.rst, aggiungerò tutti i dettagli necessari sul co-pilota per le prestazioni e creerò intestazioni per i libri, la documentazione dell'API REST e le guide di pbench. Quando l'utente fa clic su una delle intestazioni, si aprirà tutti i materiali di documentazione sotto quell'intestazione.

NOTA: il design della pagina dell'indice verrà modificato secondo il consenso dei mentori e dei membri della community e cambierà in base alle esigenze e ai requisiti.

Il file index.rst verrà incorporato in index.html nella nostra directory di output della documentazione (in genere _build/html/index.html). Una volta che la documentazione di Sphinx è in un repository pubblico, possiamo iniziare a utilizzare Leggi i documenti importando i nostri documenti.

Quando aggiungiamo un file .rst alla nostra documentazione, che corrisponde al file corrispondente, vengono generati altri tre file, uno nella cartella doctrees con estensione .doctree, il secondo nella cartella HTML con estensione .html e il terzo nella cartella html/_sources con estensione .rst.txt.

  1. HOSTING DELLA DOCUMENTAZIONE: L'hosting della documentazione su internet prevede due passaggi: 1. Importazione della documentazione: come primo passaggio, collegherò l'account Read The Docs a GitHub e importerò il nostro progetto di documentazione da creare. 2. Creazione della documentazione: entro pochi secondi dal completamento del processo di importazione, il codice verrà recuperato automaticamente dal nostro repository pubblico e verrà creata la documentazione.

  2. WEBHOOK: Il metodo principale utilizzato da Leggi i documenti per rilevare le modifiche apportate alla documentazione e alle versioni è l'uso di webhook. I webhook vengono configurati con il nostro provider di repository, ad esempio GitHub, e a ogni commit, unione o altra modifica apportata al nostro repository viene inviata una notifica a Leggi i documenti. Quando riceviamo una notifica relativa al webhook, determiniamo se la modifica è correlata a una versione attiva del progetto e, in caso affermativo, viene attivata una build per quella versione.

In questo modo chiunque (amministratori, mentori, collaboratori della community) può modificare, estendere o gestire la documentazione della community e non sarà necessario un particolare gruppo di utenti limitato per occuparsi di ciò che deve essere aggiunto alla documentazione o di ciò che deve essere rimosso dalla documentazione.

  1. TEMI: temi, layout, design e altre funzionalità HTML come la ricerca saranno conformi alle esigenze e alle linee guida della community. Durante il periodo di legame tra comunità, ne parlerò con i membri della community.
  1. OBIETTIVO DI ALLUNGAMENTO: Come obiettivo di stretching, migliorerò i diagrammi presenti nella documentazione. Attualmente, i diagrammi sono per lo più semplici disegni in bianco e nero. Introdurrò più colori, ombreggiature, scala, coerenza e un aspetto generalmente più ordinato / più professionale delle immagini.

A questo scopo, utilizzerò disegno.io (o qualsiasi altro strumento con il consenso del mentore).

Come Proof of Concept, ho migliorato uno dei diagrammi presenti nella documentazione con l'aiuto diDraw.io. Lo trovi qui: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHAttributionumKZVfc/edit?usp=sharing

PROVA DI CONCETTO

Ho convertito una piccola parte del libro PCP (formato docbook) nel primo formato e l'ho ospitata sul sito readthedocs. Puoi trovarlo qui.

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

Ho anche configurato webhook nel repository di codice, con l'aiuto dei quali, le modifiche apportate nel repository di codice verranno riflesse sul sito web.

CRONOLOGIA E CONTENUTI CONSEGNATI

PERIODO DI COMMUNITY BONDING [ 17 agosto - 13 settembre 2020 ]

Dedicherò questo tempo a familiarizzare con la community, a esaminare la documentazione e a discutere molte cose con i mentori per assicurarmi che non vengano prese decisioni sbagliate all'inizio del processo. Durante questo periodo parlerò di temi, layout, design e altre funzionalità come la ricerca, la barra di navigazione e così via con i mentori e i membri della community. Durante il periodo di legame tra comunità, verrà discussa la decisione per il nome del progetto e se ci sarà un unico sito web per ospitare tutti e tre gli argomenti o tre diversi siti web corrispondenti ai tre argomenti.

PERIODO DI SVILUPPO DELLA DOC [ 14 settembre - 30 novembre 2020 ]

***Dal 14 settembre 2020 al 20 settembre 2020 [SETTIMANA 1] Conversione dei contenuti dei documenti nel primo formato per i primi quattro capitoli della guida per utenti e amministratori.

***Dal 21 settembre 2020 al 27 settembre 2020 [WEEK 2] Conversione dei contenuti del documento nel primo formato per i prossimi quattro capitoli della guida per utenti e amministratori.

***Dal 28 settembre 2020 al 4 ottobre 2020 [SETTIMANA 3] Conversione dei contenuti del docbook nel primo formato per tutti i quattro capitoli della Guida del programmatore.

***Dal 5 ottobre 2020 all'11 ottobre 2020 [WEEK 4] - Hosting di entrambi i libri del PCP sul sito readthedocs. - Conversione della documentazione dell'API REST dalla pagina man al primo formato. Durante questo periodo, verrà trattata la pagina di destinazione principale. - Blog (del mio progetto GSoD) nelle ultime tre settimane e nella settimana in corso.

***Dal 12 ottobre 2020 al 18 ottobre 2020 [SETTIMANA 5] Conversione dell'indice Scalable Time Series nel primo formato. L'indice scalabile delle serie temporali copre i seguenti elementi: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***Dal 19 ottobre 2020 al 25 ottobre 2020 [SETTIMANA 6] Conversione dell'indice dei servizi host PMAPI nel primo formato. L'indice dei servizi host PMAPI comprende i seguenti elementi: 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

***Dal 26 ottobre 2020 al 1° novembre 2020 [SETTIMANA 7] - Se nelle ultime settimane rimane qualcosa, sarà coperto per primo. - Hosting della documentazione relativa all'API REST sul sito readthedocs. - Blog (del mio progetto GSoD) per le ultime due settimane e la settimana in corso.

***Dal 2 novembre 2020 all'8 novembre 2020 [WEEK 8] Conversione dei contenuti di markdown nel primo formato per le guide di pbench.

***Dal 9 novembre 2020 al 15 novembre 2020 [SETTIMANA 9] - È proseguita la conversione dei contenuti di markdown nel primo formato per le guide di Pbench. - Hosting delle guide di pbench sul sito di readthedocs. - Blog (del mio progetto GSoD) per l'ultima settimana e la settimana corrente.

***Dal 16 novembre 2020 al 22 novembre 2020 [SETTIMANA 10] - Implementazione della funzionalità di ricerca nella pagina dell'indice per la ricerca di contenuti del suo nome nei siti web. - Inizio degli obiettivi di stretching.

***Dal 23 novembre 2020 al 30 novembre 2020 [SETTIMANA 11] - Miglioramento di tutti i diagrammi presenti nella documentazione. - Il blog finale (del mio progetto GSoD) per l'ultima settimana e la settimana in corso. - Controllare se il codebase è conforme o meno agli standard di codifica. In caso contrario, impostali sugli standard.

PERIODO DI FINALIZZAZIONE DEL PROGETTO [ 30 novembre - 5 dicembre 2020 ]

  • Tempo di inattività con la matita. Stiamo lavorando all'invio finale per accertarsi che sia tutto a posto.
  • Invio dei report sul progetto, noti anche come prodotti di lavoro finali.
  • Invio delle valutazioni dei progetti riusciti e dell'esperienza lavorativa con i mentori.