Informationen zum Projekt Code

Diese Seite enthält die Details zu einem Projekt für technische Angelegenheiten, das für die Google-Saison der Dokumente angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:
AboutCode
Technischer Redakteur:
ayansinha
Projektname:
Referenz für Befehlszeilenoptionen in scancode-toolkit und Neustrukturierung der Struktur der AboutCode-Dokumentation unter aboutcode.readthedocs.io
Projektdauer:
Standardlänge (3 Monate)

Projektbeschreibung

[ 1. Befehlszeilenoptionen für das Scancode-Toolkit ]

Das Scancode-Toolkit bietet eine Reihe von Befehlszeilenoptionen, mit denen Sie die Durchführung des Scans, das Ausgabeformat und verschiedene andere Optionen wie Plug-ins für die Zeit nach dem Scan anpassen können. Für diese Optionen gibt es derzeit keine angemessene Dokumentation, um sie zu erklären. Sie sind nur über die Flags „--help“ oder „-h“ verfügbar. Dieses Projekt zielt darauf ab, eine vollständige Dokumentation zu erstellen, in der Folgendes erläutert wird:

[ 1. Alle über die Befehlszeile verfügbaren Optionen ]

  • Ziel: Eine vollständige Liste aller möglichen Optionen über die Befehlszeile.
  • Allgemeine Übersicht: Zuerst werden die Standard-Scanoptionen mit einem Beispiel für die Ausgabe erläutert. Eine kurze Grafik/Beschreibung dazu, wie der Scan durchgeführt wird.
    Im Folgenden dient dieses Standardverhalten als Referenz dafür, wie sich die anderen Optionen auf den Scan und die Ausgabe auswirken.
    Diese sollen ausführlich besprochen werden. Sie enthalten die folgenden Informationen, wie in den nächsten Abschnitten erwähnt.

[ 2. Versionierungsstruktur initiieren ]

  • Ziel: Ein Versionierungssystem einrichten, um Release-übergreifende Optionen/API- und Dokumentationsänderungen ordnungsgemäß zu verwalten.
  • Problem: Die Dokumentation im Wiki und auf den ReadTheDocs-Seiten bezieht sich derzeit auf ältere Releases und muss grundlegend umstrukturiert werden.
  • Grundlegender Überblick: Die Teile des Scancode-Toolkits, die aktualisiert wurden bzw. in der Version aktualisiert werden könnten, sind
  • Befehlszeilenoptionen
  • APIs
  • Dokumentation (wird initiiert) Die Befehlszeilenoptionen und APIs werden in Versionen und Releases geändert. Die Dokumentation muss dies ebenfalls widerspiegeln, da es sonst zu großer Verwirrung bei den Nutzern kommt. Das Befehlszeilen-Dienstprogramm [ --help ] ist bereits auf alle Änderungen an den Optionen aktualisiert und kann verwendet werden, um die Versionierung in der Dokumentation zu replizieren.

[ 3. Wie diese Optionen in verschiedenen Fällen verwendet werden können ]

  • Ziel: Dieser Abschnitt enthält eine grundlegende Zusammenfassung dazu, wie die Scanergebnisse des Scancode-Toolkits für verschiedene Zwecke verwendet werden können, und die Scancode-Toolkit-Optionen, die solche Funktionen bieten.
  • Grundlegende Übersicht: In diesem Abschnitt finden Sie Beispiele für verschiedene Anwendungsfälle und die in diesen Fällen empfohlenen Optionen.
  • Hinweis: Dieser Teil erfordert umfangreiche Hilfe des Mentors in Bezug auf Eingaben und Verweise auf verschiedene Anwendungsfälle des Scancode-Toolkits.

[ 4. Auswirkungen dieser Optionen auf den Scan und die Ausgabe ]

  • Ziel: In diesem Abschnitt wird eine grundlegende Zusammenfassung der Möglichkeiten zur Verwendung der Scanergebnisse des Scancode-Toolkits für verschiedene Zwecke und die Aboutcode-Tools beschrieben, die diese Funktionen bieten.
  • Grundlegende Übersicht: Mit den Optionen wird das Verhalten des Scans geändert. Im ersten Abschnitt [ 1. In diesem Abschnitt werden alle Optionen verglichen, die über die Befehlszeile verfügbar sind, und die Auswirkungen auf dieses Standardszenario.

[ 5. Ausgabeformate und Beispiele ]

  • Ziel: In diesem Abschnitt wird eine grundlegende Zusammenfassung der Möglichkeiten zur Verwendung der Scanergebnisse des Scancode-Toolkits für verschiedene Zwecke und die Aboutcode-Tools beschrieben, die diese Funktionen bieten.
  • Grundlegende Übersicht: Das Scancode-Tool bietet Flags, mit denen verschiedene Ausgabeformate für die Scanergebnisse angegeben werden können. Das sind:
    Dieser Teil wird
  • die Ausgabeformate ausführlich erläutern
  • geben Sie Beispiele für die Ausgabeformate.
  • andere Links zum Ausgabeformat und seiner Verwendung angeben
  • wie die Scanergebnisse in den Ausgabedateien gespeichert werden. Dieser Link enthält auch einen Link zur Generierung dieser verschiedenen Formate, die in [ 2. Diskussionen zum Scannen von Code ].

[ 6. Verwendung von Scancode-Ausgabeformaten für Geschäftszwecke ]

  • Ziele: Geschäftsanwendungsfälle von Scancode-Ausgabeformaten erläutern In der GSoD-Ideenliste wird „Scancode-Ausgabeformate“ als Referenzidee erwähnt. In diesem Abschnitt wird das Gleiche implementiert.
  • Hinweis: Für diesen Teil ist umfangreiche Unterstützung durch den Mentor erforderlich, z. B. in Form von Informationen und Hinweisen zu verschiedenen geschäftlichen Anwendungsfällen des Scancode-Toolkits.

[ 7. Wie diese Ergebnisse von anderen AboutCode-Projekten für weitere Analysen verwendet werden ]

  • Ziel: In diesem Abschnitt wird eine grundlegende Zusammenfassung der Möglichkeiten zur Verwendung der Scanergebnisse des Scancode-Toolkits für verschiedene Zwecke und die Aboutcode-Tools beschrieben, die diese Funktionen bieten.
  • Grundlegende Informationen:
  • Scancode-Workbench In diesem Abschnitt wird die Visualisierung von Ergebnissen mit der Desktop-App erläutert. Außerdem finden Sie Verweise auf die Scancode-Workbench-Dokumentation, in der Sie weitere Informationen dazu finden. Fügen Sie bei Bedarf die erforderliche Dokumentation zur Scancode-Workbench hinzu.
  • Deltacode So werden Scancode-Ergebnisse von Deltacode verwendet, um Unterschiede auf Dateiebene zwischen zwei Codebases zu ermitteln.

[ 2. Struktur der AboutCode-Dokumentation neu organisieren ]

Dieser Teil enthält eine Reihe von Änderungen an der Aboutcode-Dokumentation.

[ 1. Versionierungssystem ]

In [ 1. Scancode-Toolkit-Befehlszeilenoptionen –> 2. Initiate Versioning Structure] wird das Problem der Versionierung der Befehlszeilenoptionen erwähnt. Dasselbe gilt für andere Teile der Dokumentation, die versionsspezifische Befehle/Informationen enthalten, die sonst für Verwirrung sorgen würden.

[ 2. Dokumentationsstandards und ‑tests festlegen ]

Die Dokumentation enthält bereits Tests für spinx-build (erstellt alle Seiten und prüft sie auf Sphinx-Syntaxfehler) und Link-Check (prüft alle Links zu anderen Webseiten in der Dokumentation) mit Continuous Integration über Travis-CI. (Von mir in diesem Pull-Request #17 hinzugefügt) Jetzt sind weitere Prüfungen für bestimmte Lint-Regeln in reStructured Text und anderen Standards erforderlich. Dies könnte mit „restructuredtext-lint“ erreicht werden, erfordert aber weitere Recherchen und wird im Rahmen meines GSoD-Projekts durchgeführt.

[ 3. Abschnitt „Erste Schritte“ hinzufügen ]

Dieser Abschnitt dient als Ausgangspunkt für Neulinge und enthält eine Zusammenstellung der wichtigsten und grundlegendsten Dokumente für den Einstieg in Aboutcode-Projekte. Jeder Aboutcode-Code enthält diesen Abschnitt, einschließlich Scancode-Toolkit, Scancode-Workbench und Deltacode.

[ 4. Umstrukturierung gemäß den vier Dokumentfunktionen ]

Die vorhandene Dokumentation ist in den vier Dokumentfunktionen – Tutorials, Anleitungen, Referenz und Erläuterungen – nicht explizit strukturiert. Ich schlage vor, diese entsprechend zu strukturieren und bei Bedarf weitere Informationen/Erläuterungen/Hinweise hinzuzufügen. Das gilt für alle AboutCode-Projekte und ihre Dokumentation. Unten finden Sie zwei Beispiele für die Umstrukturierung der Scancode-Toolkit-Dokumentation, die ich vorschlage und in diesem Projekt fortsetzen möchte. Ähnliche Änderungen werden auch an der restlichen Dokumentation vorgenommen.

[ 5. Neustrukturierung der Seite „Entwicklung“ (Scancode-Toolkit) ]

Möglicherweise werden weitere Informationen zum Code/APIs hinzugefügt, um ihn entwicklerfreundlicher zu gestalten. Es können Links zum [ 2. Diskussionen, in denen der Abschnitt „Code-Scanning“ oben erläutert wird. So wird die Funktionsweise des Scans mit dem Code verknüpft, der für die Durchführung des Scans verwendet wird. Da diese Ordner verschiedene Teile des Scancode-Toolkits enthalten, kann ihre individuelle Verwendung mit den APIs in Verbindung mit der Diskussion zur Funktionsweise von Scancodes erläutert werden.

  • [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
  • [ commoncode : helper classes and functions]
  • [ extractcode : verschiedene Archivformate extrahieren ]
  • [ formattedcode : Ausgabeformat für verschiedene Ausgabedateiformate ]
  • [ licensedcode : licence detection code ]
  • [ packagedcode : Parsen verschiedener Paketformate ]
  • [ plugincode : classes for the plugins architecture ]
  • [ summarycode : summarizes scan on detected licenses ]
  • [ textcode : handles text parsing ]
  • [ typecode : handles file type determinations ]
  • [ scancode : CLI and API to scancode, the core part ]

Dieser Abschnitt enthält entsprechende detaillierte Informationen/APIs zu diesen Teilen des Scancode-Toolkits. Die Entwicklungsrichtlinien befinden sich auf einer anderen Seite oder in einem anderen Abschnitt mit kleineren Unterabschnitten.

[ 6. Neustrukturierung der FAQ-Seite (Scancode-Toolkit) ]

Die Seite mit häufig gestellten Fragen enthält derzeit Fragen, die besser beantwortet werden können und als separate Anleitungen, Tutorials und Referenzdokumente strukturiert werden sollten.

  • Wie funktioniert ScanCode? Dieses Problem wird in [ 2. Diskussionen, in denen das Scannen des Codes erläutert wird]. Die Diskussionen sind ein separater Abschnitt mit weiteren Details.
  • Wie füge ich neue Lizenzregeln für die erweiterte Erkennung hinzu? Dieses Problem wurde bereits im Abschnitt „Verbesserung der vorhandenen Anleitungen“ besprochen. Die Dokumentation wird dorthin verschoben.
  • Wie füge ich eine neue Lizenzerkennungsregel hinzu? Das könnte in einem separaten „Anleitung“-Beitrag ausführlicher erläutert werden.
  • Erste Schritte mit der Entwicklung Es gibt bereits eine separate Entwicklerseite und die Informationen überschneiden sich ziemlich häufig. Die Umstrukturierung der Seite „Entwicklung“ wurde bereits oben erläutert.
  • Schritte zum Schneiden eines neuen Releases Dieser Abschnitt kann in ein separates „How To Cut a new release“ umgewandelt werden.
  • Hier finden Sie weitere FAQs, in denen allgemeine Fragen zum Projekt beantwortet werden, die nicht in die Kategorien „Anleitung“ und „Tutorial“ fallen.