Questa pagina contiene i dettagli di un progetto di redazione tecnica accettato per Google Season of Docs.
Riepilogo del progetto
- Organizzazione open source:
- AboutCode
- Technical Writer:
- ayansinha
- Nome del progetto:
- Reference for Command Line Options in scancode-toolkit and Reorganize the structure of AboutCode documentation at aboutcode.readthedocs.io
- Durata del progetto:
- Durata standard (3 mesi)
Project description
[ 1. Opzioni della riga di comando di Scancode-Toolkit ]
Scancode-Toolkit offre una serie di opzioni della riga di comando per personalizzare la modalità di esecuzione della scansione, il formato di output e diverse altre opzioni, come i plug-in post-scansione. Queste opzioni al momento non hanno una documentazione adeguata che le spieghi 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 illustrate le opzioni di scansione predefinite, con un esempio dell'output. Una breve grafica/descrizione su come viene eseguita la scansione.
D'ora in poi, questo comportamento predefinito fungerà da riferimento per capire in che modo le altre opzioni modificano la scansione e l'output.
Questi aspetti verranno discussi in dettaglio e conterranno le informazioni indicate nelle sezioni successive.
[ 2. Avvia la struttura di controllo delle versioni ]
- Obiettivo: avviare un sistema di controllo delle versioni per gestire correttamente le opzioni/API e le modifiche alla documentazione tra le release.
- Problema: al momento, la documentazione nel wiki e nelle pagine ReadTheDocs riguarda le release precedenti e necessita di una riorganizzazione importante.
- Panoramica di base: le parti di Scancode-Toolkit che sono state aggiornate/potrebbero essere aggiornate nella versione sono
- Opzioni della riga di comando
- API
- Documentazione (da avviare) Le opzioni della riga di comando e le API vengono modificate nelle versioni e nelle release e anche la documentazione deve essere aggiornata, altrimenti si creerà una grande confusione per gli utenti. L'utilità della riga di comando [ --help ] è già aggiornata per 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 di Scancode-Toolkit che forniscono questa funzionalità.
- Panoramica di base: questa sezione fornisce diversi esempi di scenari di casi d'uso e le opzioni consigliate in questi scenari.
- Nota: questa parte richiede un aiuto significativo da parte del mentor in termini di input e indicazioni sui vari casi d'uso di Scancode-Toolkit.
[ 4. Cosa modificano queste opzioni nella scansione e nell'output ]
- Obiettivo: questa sezione fornirà un riepilogo di base di come i risultati della scansione di Scancode-Toolkit possono essere utilizzati in diverse cause e degli strumenti AboutCode che forniscono questa funzionalità.
- Panoramica di base: le opzioni modificano il comportamento di esecuzione della scansione. Nella sezione principale [ 1. Tutte le opzioni disponibili tramite la riga di comando ] verrà illustrato un caso predefinito di base e in questa sezione verranno confrontate le modifiche che tutte le opzioni apportano a questo scenario predefinito.
[ 5. Formati di output ed esempi ]
- Obiettivo: questa sezione fornirà un riepilogo di base di come i risultati della scansione di Scancode-Toolkit possono essere utilizzati in diverse cause e degli strumenti AboutCode che forniscono questa funzionalità.
- Panoramica di base: Scancode-Tool ha flag per specificare diversi formati di output in cui verranno generati i risultati della scansione. Questi sono -
Questa parte - spiegherà in dettaglio i formati di output
- fornirà esempi sui formati di output
- fornirà altri link corrispondenti al formato di output e al suo utilizzo
- spiegherà come i risultati della scansione vengono archiviati nei file di output. Viene inoltre fornito un link a Come vengono generati questi diversi formati, che verrà spiegato in [ 2. Discussioni che spiegano la scansione del codice ].
[ 6. Utilizzo aziendale dei formati di output di Scancode ]
- Obiettivi: spiegare i casi d'uso aziendali dei formati di output di Scancode. Nell'elenco delle idee di GSoD, i formati di output di Scancode sono indicati come idea di riferimento. Questa sezione implementa la stessa idea.
- Nota: questa parte richiede un aiuto significativo da parte del mentor in termini di input e indicazioni sui vari casi d'uso aziendali di Scancode-Toolkit.
[ 7. Come questi output vengono utilizzati da altri progetti AboutCode per ulteriori analisi ]
- Obiettivo: questa sezione fornirà un riepilogo di base di come i risultati della scansione di Scancode-Toolkit possono essere utilizzati in diverse cause e degli strumenti AboutCode che forniscono questa funzionalità.
- Panoramica di base:
- Scancode-Workbench Questa parte spiega come visualizzare i risultati con l'app desktop e fornisce indicazioni sulla documentazione di Scancode-Workbench per ulteriore assistenza. Se necessario, aggiungerò la documentazione richiesta a Scancode-Workbench.
- Deltacode Come i risultati di Scancode vengono utilizzati da 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 di Scancode-Toolkit -> 2. Avvia la struttura di controllo delle versioni] viene menzionato il problema del controllo delle versioni delle opzioni della riga di comando. Lo stesso vale anche per altre parti della documentazione che contengono comandi/informazioni specifici della versione che altrimenti creerebbero confusione.
[ 2. Impostare standard e test di documentazione ]
La documentazione ha già test per spinx-build (crea tutte le pagine e verifica la presenza di errori di sintassi Sphinx) e link check (verifica tutti i link ad altre pagine web dalla documentazione) con l'integrazione continua tramite Travis-CI. (Aggiunto da me in questa richiesta di pull #17 ) Ora sono necessari ulteriori controlli per il linting specifico in reStructured Text e altri standard. Questo potrebbe essere ottenuto con restructuredtext-lint, ma sono necessarie ulteriori ricerche e verrà eseguito nell'ambito del mio progetto GSoD.
[ 3. Aggiungere una sezione "Guida introduttiva" ]
Questa sezione fungerà da punto di partenza per i nuovi utenti e conterrà una raccolta dei documenti più basilari e importanti per iniziare a utilizzare i progetti AboutCode. Ogni progetto AboutCode avrà questa sezione, inclusi Scancode-Toolkit, Scancode-Workbench, Deltacode e altri.
[ 4. Ristrutturazione in base alle 4 funzioni dei documenti ]
La documentazione esistente non è strutturata in modo esplicito nelle 4 funzioni dei documenti: tutorial, guide pratiche, riferimenti e spiegazioni. Propongo di strutturarla di conseguenza, aggiungendo ulteriori informazioni/spiegazioni/indicazioni, se necessario. 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. Ristrutturare la pagina di sviluppo (Scancode-Toolkit) ]
Potrebbero essere aggiunte ulteriori informazioni sul codice/sulle API per renderlo più adatto agli sviluppatori. Potrebbero essere presenti link alla sezione [ 2. Discussioni che spiegano la scansione del codice ] sopra. In questo modo, la spiegazione del funzionamento della scansione viene collegata al codice utilizzato per eseguirla. Poiché queste cartelle contengono diverse parti di Scancode-Toolkit, il loro utilizzo individuale può essere elaborato con le API, in combinazione con la discussione sul funzionamento di Scancode.
- [ cluecode : plug-in per la scansione di licenze, copyright, URL, email ]
- [ commoncode : classi e funzioni di assistenza]
- [ extractcode : estrae diversi formati di archivio ]
- [ formattedcode : formattazione dell'output per diversi formati di file di output ]
- [ licensedcode : codice di rilevamento delle licenze ]
- [ packagedcode : analisi di vari formati di pacchetti ]
- [ plugincode : classi per l'architettura dei plug-in ]
- [ summarycode : riepiloga la scansione delle licenze rilevate ]
- [ textcode : gestisce l'analisi del testo ]
- [ typecode : gestisce le determinazioni del tipo di file ]
- [ scancode : CLI e API per Scancode, la parte principale ]
Questa sottosezione conterrà informazioni/API dettagliate su queste parti di Scancode-Toolkit nelle sottosezioni corrispondenti. Le linee guida per lo sviluppo saranno disponibili in un'altra pagina o in un'altra sezione con sottosezioni più piccole.
[ 6. Ristrutturare la pagina delle domande frequenti (Scancode-Toolkit) ]
Al momento, la pagina delle domande frequenti contiene domande a cui è possibile rispondere meglio e che dovrebbero essere strutturate come documenti separati di guide pratiche, tutorial e riferimenti.
- Come funziona ScanCode? Questo problema viene trattato in [ 2. Discussioni che spiegano la scansione del codice ] e sarà una sezione completamente separata con molti più dettagli.
- Come aggiungere nuove regole di licenza per un rilevamento avanzato? Questo problema è già stato discusso in precedenza in Migliorare le guide pratiche esistenti, la documentazione verrà spostata lì.
- Come aggiungere una nuova regola di rilevamento delle licenze? Questa potrebbe essere trasformata in un altro post di "guida pratica" separato e potrebbe essere elaborata.
- Come iniziare a sviluppare? Esiste già una pagina di sviluppo separata e le informazioni si sovrappongono parecchio. La ristrutturazione della pagina di sviluppo è già stata discussa in precedenza.
- Passaggi per creare una nuova release Questa operazione può essere trasformata in una "guida pratica" separata.
- Trova altre domande frequenti che rispondono a domande generiche sul progetto e che non rientrano nelle categorie "guida pratica"/"tutorial".