Progetto co-pilota per prestazioni

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

Riepilogo del progetto

Organizzazione open source:
Co-pilota per il rendimento
Redattore tecnico:
arzoo14
Nome del progetto:
Converti i contenuti delle aree dei progetti di libri in formato readthedocs e reStructuredText, oltre all'obiettivo di miglioramento dei diagrammi.
Durata del progetto:
Durata standard (3 mesi)

Project description

ASTRUTTO:

Il sito web della community svolge un ruolo essenziale in un'organizzazione open source perché diffonde l'idea delle offerte fornite dalla community, dei suoi preziosi contributi, delle loro competenze, delle loro documentazioni, dei loro tutorial, ecc. Quindi, il mio progetto punterà ad aumentare l'usabilità e la facilità per tutti i collaboratori open source trasferendo e aggiornando i contenuti delle aree di progetto del libro, ad esempio i contenuti del docbook, la documentazione dell'API REST e i contenuti del formato di lettura dei testi iorench su questo sito. Questo progetto sarà utile anche ai collaboratori della community, che potranno modificare ed estendere più facilmente questi contenuti. Inoltre, come obiettivo ambizioso, i diagrammi nella documentazione verranno migliorati per dare loro un aspetto più professionale.

PROPOSTA:

  1. PANORAMICA: la documentazione di Performance Co-Pilot è attualmente disponibile in diversi formati. Sono inclusi i libri PCP in formato docbook, l'API REST in formato manpage e le guide pbench in formato Markdown. Pertanto, l'attuale gruppo di manutentori dell'organizzazione ha capito di aver bisogno di una soluzione che sia il più possibile priva di manutenzione e che consenta alla community degli sviluppatori di concentrarsi interamente sulla manutenzione dei propri contenuti in modo semplice e snello. Pertanto, in base alle esigenze attuali dell'organizzazione, implementerò i seguenti obiettivi durante la Stagione dei documenti di Google:

    1. Conversione dei contenuti del docbook in formato reStructuredText e ospitarli sul sito di readthedocs.
    2. Conversione della documentazione dell'API REST dalla pagina di manuali a un formato adatto agli sviluppatori, ad esempio il formato reStructuredText, e hosting sul sito readthedocs.
    3. Conversione dei contenuti pbench Markdown in formato reStructuredText e ospitarli sul sito readthedocs.
    4. Gli obiettivi ambiziosi potrebbero essere migliorare i diagrammi presenti nella documentazione.

  2. IMPLEMENTAZIONE: al momento la documentazione di Performance Co-Pilot non è disponibile in un formato specifico. Ogni volta che i contenuti della documentazione devono essere modificati, devono essere modificati da un gruppo ristretto di utenti. Non è così facile per i membri attivi della community modificare ed estendere i contenuti della documentazione.

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

Read the Docs (RTD) semplifica la documentazione del software automatizzando la compilazione, la gestione delle versioni e l'hosting delle nostre documentazioni. È una piattaforma di hosting per la documentazione generata da Sphinx. Sfrutta la potenza di Sphinx e aggiunge il controllo della versione, la ricerca full-text e altre funzionalità utili. Recupera i file di codice e della documentazione da Git, Mercurial o Subversion, quindi compila e ospita la nostra documentazione. Utilizzeremo GitHub nel nostro progetto in quanto è il sistema più comunemente utilizzato per accedere al codice.

Per iniziare, creeremo un account Read the Docs e collegheremo l'account GitHub. Selezioneremo quindi il repository GitHub per il quale vogliamo creare la documentazione. A quel punto, avverrà la magia.

Leggi i documenti per: - Clonare il nostro repository. - Crea le versioni HTML, PDF ed EPUB della nostra documentazione dal nostro ramo principale. - Indicizza la nostra documentazione per consentire la ricerca in testo completo. - Crea oggetti Version da ogni tag e ramo del nostro repository, il che ci consente di ospitarli facoltativamente. - Attivare un webhook nel repository, in modo che quando eseguiamo il push del codice a qualsiasi ramo, la nostra documentazione viene ricreata.

Sphinx è un generatore di documentazione autorevole che ha molte ottime 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 la documentazione. - Un ampio sistema di codici e documentazione per riferimenti incrociati. - Esempi di codice evidenziati per la sintassi. - Un ecosistema vivace di estensioni proprietarie e di terze parti.

Inizierò con la conversione dei due libri PCP presenti nel formato docbook nel formato rst, dopo la conversione della documentazione dell'API REST dal formato della pagina man al formato rst, poi la conversione dei contenuti markdown pbench in formato rst e, alla fine, ospitando tutti questi sul sito readthedocs. Gli obiettivi aggiuntivi sono quelli di migliorare i diagrammi nella documentazione.

2.1. Conversione in formato reStructuredText: Il primo passaggio consisterà nel convertire i contenuti della documentazione in formato reStructuredText. Ogni capitolo avrà un file rst separato, che conterrà solo i contenuti del capitolo. Ad esempio, la Guida per gli utenti e gli amministratori di Performance Co-Pilot include otto capitoli. Significa che ci saranno otto diversi primi file corrispondenti a questi otto capitoli. Il nome del file RST sarà uguale al nome del capitolo per evitare confusione in futuro. Un elenco di figure, tabelle ed elenchi di esempi sarà presente in tre diversi file rst. I primi contenuti avranno un link ipertestuale completo, così come sono attualmente presenti. La stessa cosa verrà usata per la documentazione dell'API REST e per i contenuti pbench. Tutti gli aspetti necessari, come grassetto, corsivo, sottolineatura, elenchi puntati, tabelle, dimensioni del carattere, stile del codice, dimensioni dell'immagine, allineamento e così via, verranno gestiti durante la conversione dei contenuti nel formato primo.

2.2. Integrazione del primo con Sphinx:

ReadtheDocs utilizza Sphinx e reStructuredText (rst) come valori predefiniti. Poiché Sphinx è preinstallata nel mio sistema, inizierò con la creazione di una directory all'interno del progetto (denominata Performance Co-Pilot Documentazione) per contenere i documenti: $ cd /path/to/project $ mkdir docs

Dopodiché, esegui sphinx-quickstart: $ cd docs $ sphinx-quickstart

Questa guida rapida illustra la 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, un file conf.py e alcuni altri file. In index.rst aggiungerò tutti i dettagli necessari su Performance Co-Pilot 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, vengono aperti tutti i materiali della documentazione sotto quella intestazione.

NOTA: il design della pagina di indice sarà in base al consenso dei mentor e dei membri della community e verrà modificato in base alle esigenze e ai requisiti.

Il file index.rst verrà incorporato in index.html nella 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 aggiungeremo un file .rst nella nostra documentazione corrispondente a quel file, verranno 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 con GitHub e importerò il nostro progetto di documentazione da compilare. 2. Creazione della documentazione: entro pochi secondi dal completamento della procedura di importazione, il codice verrà recuperato automaticamente dal nostro repository pubblico e verrà creata la documentazione.

  2. WEBHOOK: Il metodo principale utilizzato da Read the Docs per rilevare le modifiche alla documentazione e alle versioni è l'utilizzo di webhook. Gli webhook vengono configurati con il nostro provider di repository, ad esempio GitHub, e ogni commit, unione o altra modifica al nostro repository viene inviata una notifica a Read the Docs. Quando riceviamo una notifica webhook, stabiliamo se la modifica è correlata a una versione attiva del nostro progetto e, in questo caso, viene attivata una compilazione per quella versione.

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

  1. TEMI: temi, layout, progetti e altre funzionalità HTML come la ricerca si baseranno sulle esigenze e sulle linee guida della community. Durante il periodo di affiatamento con la community, ne parlerò con i membri della community.
  1. OBIETTIVO DI STRETCH: Come obiettivo aggiuntivo, migliorerò i diagrammi presenti nella documentazione. Al momento, i diagrammi sono per lo più semplici disegni in bianco e nero. Presenterò più colori, ombreggiatura, ridimensionamento, coerenza e un aspetto generalmente più ordinato / più professionale delle immagini.

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

Come proof of concept, ho migliorato uno dei diagrammi presenti nella documentazione con l'aiuto di draw.io. Si trova qui: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

PROVA DI CONCETTO

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

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

Ho anche configurato gli webhook nel repository del codice, grazie ai quali le modifiche apportate nel repository del codice verranno applicate al sito web.

CRONOLOGIA E RISULTATI FINALI

PERIODO DI RAFFORZAMENTO DELLA COMUNITÀ [17 agosto - 13 settembre 2020 ]

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

PERIODO DI SVILUPPO DEL DOCUMENTO [14 settembre - 30 novembre 2020 ]

***Dal 14 settembre 2020 al 20 settembre 2020 [SETTIMANA 1] Conversione dei contenuti del docbook nel primo formato per i primi quattro capitoli della Guida per l'utente e l'amministratore.

***Dal 21 settembre al 27 settembre 2020 [SETTIMANA 2] Conversione dei contenuti del documento in formato rst per i prossimi quattro capitoli del libro Guida per utenti e amministratori.

***Dal 28 settembre 2020 al 4 ottobre 2020 [3ª SETTIMANA] Conversione dei contenuti del documento in formato rst per tutti e quattro i capitoli del libro Guida del programmatore.

***Dal 5 ottobre 2020 all'11 ottobre 2020 [SETTIMANA 4] - Hosting di entrambi i libri PCP sul sito readthedocs. - Conversione della documentazione dell'API REST dalla pagina man al formato primo. La pagina di destinazione principale verrà coperta durante questo periodo. - Pubblicazione di post 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 delle serie temporali scalabili in formato rst. L'indice delle serie temporali scalabili copre quanto segue: 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 in formato rst. L'indice dei servizi host PMAPI copre quanto segue: 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 rimangono dei problemi nelle ultime settimane, verranno risolti per primi. - Hosting della documentazione dell'API REST sul sito readthedocs. - Blogging (del mio progetto GSoD) delle ultime due settimane e della settimana in corso.

***Dal 2 novembre 2020 all'8 novembre 2020 [SETTIMANA 8] Conversione dei contenuti Markdown in formato rst per le guide di pbench.

***Dal 9 novembre 2020 al 15 novembre 2020 [SETTIMANA 9] - È stata continuata la conversione dei contenuti Markdown in formato RST per le guide di pbench. - Hosting delle guide di pbench sul sito readthedocs. - Pubblicazione di post del mio progetto GSoD per l'ultima settimana e per quella in corso.

***Dal 16 novembre 2020 al 22 novembre 2020 [SETTIMANA 10] - Implementazione della funzionalità di ricerca nella pagina dell'indice per cercare qualsiasi contenuto dal nome nei siti web. - Inizio degli obiettivi sfida.

***Dal 23 novembre 2020 al 30 novembre 2020 [WEEK 11] - Miglioramento di tutti i diagrammi presenti nella documentazione. - Il blog finale (del mio progetto GSoD) per l'ultima e la corrente settimana. - Verificare se la base di codice è conforme agli standard di programmazione. In caso contrario, modificali in base agli standard.

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

  • Tempo di riposo di Pencil. Lavorare all'invio finale e assicurarsi che tutto sia a posto.
  • Invio dei report del progetto, noti anche come prodotti finali del lavoro.
  • Invio delle valutazioni del successo dei progetti e dell'esperienza di lavoro con i mentor.