Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione di Documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- AboutCode
- Redattore tecnico:
- ayansinha
- Nome del progetto:
- Riferimento per le opzioni a riga di comando in scancode-toolkit e riorganizzazione della 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 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-scan. Queste opzioni al momento non dispongono di una documentazione appropriata per spiegarle e sono disponibili solo tramite il flag "--help" o "-h". Questo progetto mira a realizzare una documentazione completa che spieghi:
[ 1. Tutte le opzioni disponibili dalla riga di comando ]
- Obiettivo: un elenco esaustivo di tutte le opzioni possibili tramite la riga di comando.
- Panoramica di base: innanzitutto vengono discusse le opzioni di scansione predefinite, con un esempio dell'output. Una breve grafica/descrizione di come viene eseguita la scansione.
In seguito, questo comportamento predefinito funge da riferimento al modo in cui le altre opzioni modificano la scansione e l'output.
Questi 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 alle API e alla documentazione tra le release.
- Problema: al momento la documentazione nella wiki e nelle pagine di ReadTheDocs è destinata alle release precedenti e richiede una ristrutturazione importante.
- Panoramica di base: le parti del toolkit scancode 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 seguire, altrimenti verrà creata una grande confusione per gli utenti. L'utilità a 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 queste opzioni possono essere utilizzate in casi diversi ]
- Scopo: questa sezione fornisce un riepilogo di base su come i risultati dell'analisi di scancode-toolkit possono essere utilizzati in diverse cause e sulle opzioni di Scancode-Toolkit che forniscono questa funzionalità.
- Panoramica di base: questa sezione fornisce esempi di diversi scenari di casi d'uso e le opzioni consigliate in questi scenari.
- Nota: questa parte richiede un'assistenza significativa da parte del mentore in termini di input e suggerimenti per vari casi d'uso di Scancode-Toolkit.
[ 4. Che cosa cambiano queste opzioni nella ricerca e nell'output ]
- Scopo: questa sezione fornisce un riepilogo di base su come i risultati della scansione di scancode-toolkit possono essere utilizzati in diversi casi e sugli strumenti Aboutcode che forniscono questa funzionalità.
- Panoramica di base: le opzioni modificano il comportamento dell'esecuzione della scansione. Un caso predefinito di base verrà illustrato nella sezione iniziale [ 1. Tutte le opzioni disponibili tramite la riga di comando ] e questa sezione metteranno a confronto 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 in diversi casi e sugli strumenti Aboutcode che forniscono questa funzionalità.
- Panoramica di base: lo strumento Scancode ha flag per specificare diversi formati di output in cui verranno generati i risultati della scansione. Si tratta di:
Questa parte - spiegare in dettaglio i formati di output
- fornire esempi di formati di output
- fornire altri link corrispondenti al formato di output e al relativo utilizzo
- come vengono archiviati i risultati della ricerca nei file di output. Questo link rimanda anche a come vengono generati questi diversi formati, che verrà spiegato in [ 2. Discussioni che spiegano la scansione del codice ].
[ 6. Utilizzo commerciale dei formati di output degli scancode ]
- Scopi: spiegare i casi d'uso aziendali dei formati di output dello scanner Nell'elenco di idee GSoD, i formati di output dello scanner sono menzionati come idea di riferimento. Questa sezione implementa lo stesso.
- Nota: questa parte richiede un aiuto significativo da parte del mentore in termini di input e suggerimenti su vari casi d'uso aziendali di Scancode-Toolkit.
[ 7. In che modo 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 in diversi casi e sugli strumenti Aboutcode che forniscono questa funzionalità.
- Panoramica di base:
- Scancode-Workbench In questa sezione viene spiegata la visualizzazione dei risultati con l'app desktop e vengono forniti riferimenti alla documentazione di scancode-workbench per ulteriore assistenza in merito. Se necessario, aggiungerà la documentazione richiesta a scancode-workbench.
- Deltacode In che modo Deltacode utilizza i risultati della scansione per determinare le differenze a livello di file tra due codebase.
[ 2. Riorganizza la struttura della documentazione 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. Inizio della struttura di controllo delle versioni] è menzionato il problema del controllo delle versioni per le opzioni della riga di comando. Lo stesso vale per altre parti della documentazione che contengono comandi/informazioni specifici della versione che altrimenti creerebbero confusione.
[ 2. Stabilire gli standard e i test della documentazione ]
La documentazione include già test per spinx-build (crea tutte le pagine e verifica la presenza di 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. (Aggiunta da me in questa richiesta di pull #17) Ora sono necessari ulteriori controlli per linting specifici in reStructured Text e altri standard. Questo risultato potrebbe essere ottenuto con restructuredtext-lint, ma richiede ulteriori ricerche e verrà realizzato nell'ambito del mio progetto GSoD.
[ 3. aggiungendo una sezione "Per iniziare" ]
Questa sezione fungerà da punto di partenza per i nuovi arrivati e conterrà una raccolta dei documenti più importanti e di base per iniziare a utilizzare Aboutcode Projects. Ogni progetto Aboutcode avrà questa sezione, inclusi Scancode-Toolkit, Scancode-Workbench, Deltacode e altri.
[ 4. Ristrutturazione in base alle 4 funzioni di documento ]
La documentazione esistente non è strutturata esplicitamente nelle quattro funzioni dei documenti: tutorial, istruzioni, riferimento ed esempi. Propongo di strutturarli di conseguenza, aggiungendo più informazioni/spiegazioni/suggerimenti, 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 nel resto della documentazione.
[ 5. Ristrutturazione della pagina di sviluppo (Scancode-Toolkit) ]
Potrebbero essere aggiunte ulteriori informazioni sul codice e sulle API per renderlo più facile per gli sviluppatori. Possono essere presenti link a [ 2. Discussioni che spiegano la sezione Scansione codice ] sopra. Questo collega la spiegazione del funzionamento della scansione al codice utilizzato per eseguirla. Poiché queste cartelle contengono parti diverse di scancode-toolkit, il loro utilizzo individuale può essere elaborato con le API, in combinazione con la discussione sul funzionamento di scancode.
- [ cluecode : plugin per la scansione di licenze, copyright, url, email ]
- [ commoncode : helper classes and functions]
- [ extractcode : estrae diversi formati di archivio ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : classi per l'architettura dei plug-in ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : gestisce l'analisi del testo ]
- [ typecode : gestisce le determinazioni dei tipi di file ]
- [ scancode : interfaccia a riga di comando e API per scansionare, la parte principale ]
Questa sottosezione conterrà informazioni/API dettagliate su queste parti di scancode-toolkit nelle sottosezioni di conseguenza. 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 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 di riferimento, tutorial e istruzioni separati.
- Come funziona ScanCode? Questo problema è indicato 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 il rilevamento avanzato? Questo problema è già stato discusso in precedenza nell'articolo Migliorare le procedure dettagliate esistenti, dove verrà spostata la documentazione.
- Come si aggiunge una nuova regola di rilevamento delle licenze? Questi contenuti potrebbero essere inseriti in un altro post di istruzioni e approfondire ulteriormente.
- Come iniziare a utilizzare lo sviluppo? Esiste già una pagina di sviluppo separata e le informazioni si sovrappongono molto. La ristrutturazione della pagina di sviluppo è già stata discussa sopra.
- Passaggi per tagliare una nuova uscita Questa procedura può essere trasformata in una sezione "Come tagliare una nuova uscita" separata.
- Trova altre domande frequenti che rispondono a domande generiche sul progetto e non rientrano nelle categorie "Istruzioni"/"Tutorial".