Progetto AboutCode

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

Riepilogo del progetto

Organizzazione open source:
AboutCode
Technical writer:
ayansinha
Nome progetto:
Riferimento per le opzioni a riga di comando in scancode-toolkit e riorganizzare la struttura della documentazione di AboutCode all'indirizzo aboutcode.readthedocs.io
Durata del progetto:
Durata standard (3 mesi)

Project description

[ 1. Opzioni della riga di comando di Scancode-Toolkit ]

Scancode-Toolkit ha una serie di opzioni della riga di comando per personalizzare il modo in cui viene eseguita la scansione, il formato di output e diverse altre opzioni come i plug-in post-scansione. Al momento queste opzioni non dispongono di una documentazione appropriata per spiegarle e sono disponibili solo tramite il flag "--help" o "-h". Questo progetto mira a creare una documentazione completa che spieghi:

[ 1. Tutte le opzioni disponibili tramite la riga di comando ]

  • Obiettivo: un elenco esaustivo di tutte le opzioni possibili tramite la riga di comando.
  • Panoramica di base: innanzitutto vengono presentate le opzioni di scansione predefinite, con un esempio dell'output. Un breve grafico/descrizione del modo in cui viene eseguita la scansione.
    D'ora in poi, questo comportamento predefinito funge da riferimento al modo in cui le altre opzioni modificano la scansione e l'output.
    Questi elementi devono essere discussi in dettaglio e conterranno le seguenti informazioni, come indicato nelle sezioni successive.

[ 2. Avvia struttura di controllo delle versioni ]

  • Obiettivo: avviare un sistema di controllo delle versioni per gestire correttamente le modifiche relative a opzioni/API e documentazione in più versioni.
  • Problema: attualmente la documentazione nel wiki e nelle pagine ReadTheDocs riguarda versioni meno recenti e necessita di un'importante ristrutturazione.
  • Panoramica di base: le parti di scancode-toolkit che sono state aggiornate/che potrebbero essere aggiornate nella versione sono
  • Opzioni della riga di comando
  • API
  • Documentazione (da avviare) Le opzioni della riga di comando e le API cambiano nelle versioni e nelle release e anche la documentazione deve seguire l'articolo, altrimenti creerà molta confusione per gli utenti. L'utilità della riga di comando [ --help ] viene già aggiornata per apportare eventuali modifiche alle opzioni e potrebbe essere utilizzata per replicare il controllo delle versioni nella documentazione.

[ 3. Come utilizzare queste opzioni in diversi casi ]

  • Obiettivo: questa sezione fornirà un riepilogo di base di come i risultati della scansione di scancode-toolkit possono essere utilizzati in diverse cause e delle opzioni Scancode-Toolkit che forniscono tale funzionalità.
  • Panoramica di base: questa sezione fornisce diversi esempi di casi d'uso e le opzioni consigliate in questi scenari.
  • Nota: questa parte richiede un aiuto significativo da parte del tutor in termini di input e riferimenti a vari casi d'uso di Scancode-Toolkit.

[ 4. Cosa cambiano queste opzioni nella scansione e nell'output ]

  • Obiettivo: questa sezione fornisce un riepilogo di base su come i risultati della scansione di scancode-toolkit possono essere utilizzati per diverse cause e degli strumenti Aboutcode che forniscono questa funzionalità.
  • Panoramica di base: le opzioni modificano il comportamento dell'esecuzione della scansione. Un caso predefinito di base sarà illustrato nella sezione iniziale [ 1. Tutte le opzioni disponibili tramite la riga di comando ] e in questa sezione confronteranno le modifiche apportate da tutte le opzioni a questo scenario predefinito.

[ 5. Formati di output e relativi esempi ]

  • Obiettivo: questa sezione fornisce un riepilogo di base su come i risultati della scansione di scancode-toolkit possono essere utilizzati per diverse cause e degli strumenti Aboutcode che forniscono questa funzionalità.
  • Panoramica di base: Scancode-Tool dispone di flag per specificare i diversi formati di output in cui verranno generati i risultati della scansione. Ecco:
    Questa parte
  • spieghiamo nel dettaglio i formati di output
  • fai degli esempi sui formati di output
  • fornisci altri link corrispondenti al formato di output e al suo utilizzo
  • come vengono archiviati i risultati della scansione nei file di output. Questo link include anche il link alla sezione Come vengono generati questi diversi formati, che verrà spiegato in [ 2. Discussioni che spiegano la scansione del codice ].

[ 6. Uso commerciale dei formati di output del codice di scansione ]

  • Obiettivi: spiegare i casi d'uso aziendali dei formati di output di Scancode Nell'elenco delle idee GSoD, i formati di output di Scancode vengono menzionati come idea di riferimento. Questa sezione implementa la stessa procedura.
  • Nota: questa parte richiede un aiuto significativo da parte del tutor in termini di input e riferimenti a vari casi d'uso aziendali di Scancode-Toolkit.

[ 7. Come questi output vengono utilizzati da altri progetti AboutCode per ulteriori analisi ]

  • Obiettivo: questa sezione fornisce un riepilogo di base su come i risultati della scansione di scancode-toolkit possono essere utilizzati per diverse cause e degli strumenti Aboutcode che forniscono questa funzionalità.
  • Panoramica di base:
  • Scancode-Workbench Questa parte spiega la visualizzazione dei risultati con l'app desktop e fornisce indicazioni alla documentazione di Scancode-workbench per ulteriore assistenza sullo stesso. Se necessario, verrà aggiunta la documentazione richiesta a Scancode Workbench.
  • Deltacode La modalità di acquisizione dei risultati del codice di scansione da parte di Deltacode per determinare le differenze a livello di file tra due codebase.

[ 2. Riorganizzare la struttura della documentazione di AboutCode ]

Questa parte include una serie di modifiche alla documentazione di Aboutcode

[ 1. Sistema di controllo delle versioni ]

In [ 1. Opzioni della riga di comando Scancode-Toolkit -> 2. Avvia struttura di controllo delle versioni] viene menzionato il problema del controllo delle versioni delle opzioni della riga di comando. Lo stesso vale per altre parti della documentazione che contengono comandi/informazioni specifici di una versione che altrimenti creerebbero confusione.

[ 2. Definizione degli standard e dei test della documentazione ]

La documentazione include già test per spinx-build (crea tutte le pagine e controlla gli errori di sintassi di Sphinx) e verifica dei link (controlla tutti i link ad altre pagine web della documentazione) con l'integrazione continua tramite Travis-CI. (Aggiunto da me in questa richiesta di pull n. 17) Ora sono necessari ulteriori controlli per l'analisi tramite lint specifica del testo ristrutturato e di altri standard. Questo risultato potrebbe essere ottenuto con restructuredtext-lint, ma richiede ulteriori ricerche e verrà eseguito nell'ambito del mio progetto GSoD.

[ 3. Aggiunta di una sezione "Come iniziare" ]

Costituisce una sezione di partenza per i nuovi utenti e contiene una raccolta dei documenti più basilari e importanti per iniziare a utilizzare i progetti Aboutcode. Ogni progetto Aboutcode includerà questa sezione, che comprende Scancode-Toolkit, Scancode-Workbench, Deltacode e altre.

[ 4. La ristrutturazione in base alle 4 funzioni del documento ]

La documentazione esistente non è strutturata esplicitamente nelle quattro funzioni del documento: Tutorial, Istruzioni, Riferimenti e Spiegazioni. Propongo di strutturarli di conseguenza, aggiungendo eventualmente ulteriori informazioni/spiegazioni/consigli. Questo vale per tutti i progetti AboutCode e la relativa documentazione. Di seguito sono riportati due esempi della ristrutturazione della documentazione di Scancode-Toolkit che propongo e che vorrei portare avanti in questo progetto. Modifiche simili verranno apportate al resto della documentazione.

[ 5. Ristrutturazione della pagina di sviluppo (Scancode-Toolkit) ]

Potresti aggiungere maggiori informazioni sul codice e sulle API per agevolare gli sviluppatori. Possono essere presenti link a [ 2. Discussioni che spiegano la sezione Scansione del codice ] precedente. Questo collega la spiegazione del funzionamento della scansione al codice che utilizza per eseguirla. Così come queste cartelle contengono diverse parti di scancode-toolkit, il loro utilizzo individuale può essere elaborato con le API, insieme alla discussione su come funziona lo scancode.

  • [ cluecode : plug-in per la scansione di licenze, copyright, URL, email ]
  • [ Commoncode : classi e funzioni helper]
  • [ estratto codice : estrae diversi formati di archivio ]
  • [ formattedcode : formattazione di output per diversi formati file di output ]
  • [ codice licenza : codice rilevamento licenza ]
  • [ codice pacchetto : analisi dei vari formati di pacchetto ]
  • [ plugincode : classi per l'architettura dei plug-in ]
  • [ summarycode : riassume la scansione in base alle licenze rilevate ]
  • [ codice testo : gestisce l'analisi del testo ]
  • [ typecode : gestisce le determinazioni dei tipi di file ]
  • [ scancode : interfaccia a riga di comando e API per scancode, la parte principale ]

Questa sottosezione conterrà informazioni/API dettagliate su queste parti di scancode-toolkit all'interno delle sottosezioni pertinenti. Le linee guida per lo sviluppo saranno disponibili in un'altra pagina o in un'altra sezione con sottosezioni più piccole.

[ 6. Ristrutturazione della pagina Domande frequenti (Scancode-Toolkit) ]

Al momento, la pagina delle domande frequenti contiene domande alle quali è possibile rispondere meglio e deve essere strutturata separatamente come documenti di istruzioni, tutorial e riferimenti.

  • Come funziona ScanCode? Questo problema è menzionato in [ 2. Discussioni che spiegano la scansione del codice ] e saranno una sezione completamente separata con molti più dettagli.
  • Come si aggiungono nuove regole per le licenze per un rilevamento avanzato? Questo problema è già stato discusso in precedenza in Migliorare le istruzioni esistenti, la documentazione verrà spostata lì.
  • Come si aggiunge una nuova regola di rilevamento delle licenze? Questo potrebbe essere trasformato in un altro post di istruzioni a parte e potrebbe essere elaborato.
  • Come iniziare a usare lo sviluppo? Esiste già una pagina di sviluppo separata e le informazioni si sovrappongono piuttosto spesso. La ristrutturazione della pagina di sviluppo è già stata discussa sopra.
  • Passaggi per tagliare una nuova release Questa versione può essere trasformata in una sezione separata denominata "How To Cut a new release".
  • Puoi trovare altre domande frequenti che rispondono a domande generiche sul progetto e che non rientrano nelle categorie "Istruzioni"/"Tutorial".