Progetto AboutCode

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".