Informationen zum Projekt Code

Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:
AboutCode
Technischer Redakteur:
Ayansinha
Projektname:
Referenz zu den Befehlszeilenoptionen im scancode-Toolkit und zur Neuorganisierung der Struktur der AboutCode-Dokumentation unter aboutcode.readthedocs.io
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

[ 1. Befehlszeilenoptionen für Scancode-Toolkit ]

Das Scancode-Toolkit verfügt über eine Reihe von Befehlszeilenoptionen, mit denen Sie den Scanvorgang, das Ausgabeformat und weitere Optionen wie Plug-ins für den Post-Scan anpassen können. Für diese Optionen gibt es derzeit keine entsprechende Dokumentation. Sie sind nur über das Flag „--help“ oder „-h“ verfügbar. Dieses Projekt zielt darauf ab, eine vollständige Dokumentation zu erstellen, die Folgendes erklärt:

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

  • Ziel: Eine vollständige Liste aller möglichen Optionen über die Befehlszeile.
  • Grundlegende Übersicht: Zuerst werden die Standardscanoptionen und ein Beispiel für die Ausgabe erläutert. Eine kurze Grafik/Beschreibung zur Durchführung des Scans
    Im Folgenden dient dieses Standardverhalten als Referenz dafür, wie die anderen Optionen den Scan und die Ausgabe ändern.
    Diese Punkte werden ausführlich besprochen und enthalten die folgenden Informationen, die in den nächsten Abschnitten erläutert werden.

[ 2. Versionierungsstruktur initiieren ]

  • Ziel: Einführung eines Versionsverwaltungssystems, um Veröffentlichungsoptionen sowie API- und Dokumentationsänderungen ordnungsgemäß zu verwalten.
  • Problem: Derzeit ist die Dokumentation im Wiki und auf den ReadTheDocs-Seiten nur für ältere Versionen vorgesehen und muss daher grundlegend umstrukturiert werden.
  • Grundlegende Übersicht: Die Teile des Scancode-Toolkits, die in der Version aktualisiert wurden bzw. aktualisiert werden könnten,
  • Befehlszeilenoptionen
  • APIs
  • Dokumentation (wird eingeleitet) Die Befehlszeilenoptionen und die APIs wurden in Versionen und Releases geändert. Auch die Dokumentation muss den Vorgaben entsprechen, da dies bei den Nutzern zu einer enormen Verwirrung führen würde. Das Befehlszeilen-Dienstprogramm [ --help ] ist bereits auf Änderungen an Optionen aktualisiert und kann verwendet werden, um die Versionsverwaltung in der Dokumentation zu replizieren.

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

  • Ziel: In diesem Abschnitt wird beschrieben, wie die Scanergebnisse des Scancode-Toolkits in verschiedenen Fällen verwendet werden können und welche Scancode-Toolkit-Optionen diese Funktionen bieten.
  • Allgemeine Übersicht: In diesem Abschnitt finden Sie Beispiele für verschiedene Anwendungsfälle und die empfohlenen Optionen.
  • Hinweis: Dieser Teil erfordert erhebliche Unterstützung vom Mentor, wenn es um Eingaben und Hinweise zu verschiedenen Anwendungsfällen des Scancode-Toolkit geht.

[ 4. Was sich diese Optionen in Scan und Ausgabe ändern ]

  • Ziel: In diesem Abschnitt wird erläutert, wie die Scanergebnisse des Scancode-Toolkit für verschiedene Zwecke verwendet werden können. Außerdem werden die entsprechenden Infocode-Tools vorgestellt.
  • Grundlegende Übersicht: Die Optionen ändern die Funktionsweise des Scans. Ein einfacher Standardfall wird im vorderen Abschnitt dargestellt [ 1. Alle über Befehlszeile verfügbaren Optionen ] und in diesem Abschnitt werden die Änderungen verglichen, die alle Optionen zu diesem Standardszenario mit sich bringen.

[ 5. Ausgabeformate und ihre Beispiele ]

  • Ziel: In diesem Abschnitt wird erläutert, wie die Scanergebnisse des Scancode-Toolkit für verschiedene Zwecke verwendet werden können. Außerdem werden die entsprechenden Infocode-Tools vorgestellt.
  • Grundlegende Übersicht: Das Scancode-Tool verfügt über Flags, mit denen verschiedene Ausgabeformate angegeben werden können, in denen die Scan-Ergebnisse generiert werden. Dies sind:
    Dieser Teil bezieht sich
  • im Detail die Ausgabeformate
  • geben Beispiele zu den Ausgabeformaten an,
  • Geben Sie weitere Links zum Ausgabeformat und seiner Verwendung an.
  • wie Scanergebnisse in den Ausgabedateien gespeichert werden. Dieser Link enthält auch einen Link zur Generierung dieser verschiedenen Formate unter [ 2. Diskussionen zur Erläuterung des Codescans ].

[ 6. Geschäftliche Nutzung von Scancode-Ausgabeformaten ]

  • Ziele: Geschäftsanwendungsfälle von Scancode-Ausgabeformaten erklären In der GSoD-Ideenliste werden Scancode-Ausgabeformate als Referenz erwähnt. In diesem Abschnitt wird dasselbe implementiert.
  • Hinweis: Dieser Teil erfordert viel Unterstützung vom Mentor, wenn es um Input und Hinweise auf verschiedene geschäftliche Anwendungsfälle des Scancode-Toolkit geht.

[ 7. Wie diese Ausgaben von anderen AboutCode-Projekten für eine weitere Analyse verwendet werden ]

  • Ziel: In diesem Abschnitt wird erläutert, wie die Scanergebnisse des Scancode-Toolkit für verschiedene Zwecke verwendet werden können. Außerdem werden die entsprechenden Infocode-Tools vorgestellt.
  • Grundlegender Überblick:
  • Scancode-Workbench In diesem Teil wird die Visualisierung von Ergebnissen mit der Desktop-App und Verweise auf die Scancode-Workbench-Dokumentation erläutert. Bei Bedarf wird die erforderliche Dokumentation zu scancode-workbench hinzugefügt.
  • Deltacode So ermittelt Deltacode die Scancode-Ergebnisse, um Unterschiede auf Dateiebene zwischen zwei Codebasen zu ermitteln.

[ 2. Struktur der AboutCode-Dokumentation neu organisieren ]

Dieser Teil umfasst zahlreiche Änderungen an der Aboutcode-Dokumentation.

[ 1. Versionsverwaltung ]

In [ 1. Scancode-Toolkit-Befehlszeilenoptionen -> 2. Initiate Versioning Structure], das Problem der Versionsverwaltung der Befehlszeilenoptionen wird erwähnt. Dasselbe ist für andere Teile der Dokumentation erforderlich, die versionsspezifische Befehle/Informationen enthalten, die ansonsten zu Verwirrung führen würden.

[ 2. Festlegung von Dokumentationsstandards und Tests ]

Die Dokumentation enthält bereits Tests für Spinx-Build (erstellt alle Seiten und prüft durchgehend auf Sphinx-Syntaxfehler) und Linkprüfung (überprüft alle Links zu anderen Webseiten aus der Dokumentation) mit Continuous Integration über Travis-CI. (Von mir in dieser Pull-Anfrage Nr. 17 hinzugefügt) Jetzt sind weitere Prüfungen auf bestimmte Linting bei neu strukturiertem Text und anderen Standards erforderlich. Dies könnte mit restructuredtext-Lint erreicht werden, erfordert jedoch weitere Recherchen und wird im Rahmen meines GSoD-Projekts umgesetzt.

[ 3. Hinzufügen eines Abschnitts „Erste Schritte“ ]

Dieser Abschnitt dient als Einstieg für neue Nutzer und enthält eine Zusammenstellung der grundlegendsten und wichtigsten Dokumente für den Einstieg in Aboutcode-Projekte. In jedem Aboutcode-Projekt gibt es diesen Abschnitt, einschließlich Scancode-Toolkit, Scancode-Workbench, Deltacode usw.

[ 4. Umstrukturierung gemäß den vier Dokumentfunktionen ]

Die vorhandene Dokumentation ist nicht explizit in den vier Dokumentfunktionen strukturiert: Tutorials, Anleitungen, Referenzen und Erläuterungen. Ich schlage vor, diese entsprechend zu strukturieren und nach Bedarf weitere Informationen/Erläuterungen/Hinweise hinzuzufügen. Das gilt für alle AboutCode-Projekte und die zugehörige Dokumentation. Nachfolgend finden Sie zwei Beispiele für die Umstrukturierung der Scancode-Toolkit-Dokumentation, die ich vorschlage und in diesem Projekt weiterführen möchte. Ähnliche Änderungen werden für die restliche Dokumentation vorgenommen.

[ 5. Die Entwicklungsseite neu strukturieren (Scancode-Toolkit)

Der Code/die APIs könnten um weitere Informationen ergänzt werden, um den Code bzw. die APIs entwicklerfreundlicher zu machen. Links zu folgenden Seiten: [ 2. Diskussionen zur Erläuterung des obigen Abschnitts „Code-Scanning ]. Dadurch wird die Funktionsweise des Scans mit dem Code verknüpft, der zum Ausführen des Scans verwendet wird. Genauso wie diese Ordner verschiedene Teile des Scancode-Toolkits enthalten, können deren individuelle Verwendung mithilfe der APIs in Verbindung mit der Diskussion über die Funktionsweise von Scancode ausgefeilt werden.

  • [ CLecode : Plug-ins zum Scannen von Lizenzen, Copyright-Hinweisen, URLs, E-Mails ]
  • [ Commoncode : Hilfsklassen und Funktionen]
  • [Extractcode : Extrahiert verschiedene Archivformate ]
  • [ formattedcode : Ausgabeformatierung für verschiedene Ausgabedateiformate ]
  • [Licensecode : Lizenzerkennungscode ]
  • [packagedcode : Parsing verschiedener Paketformate ]
  • [ Plug-in-Code : Klassen für die Plug-in-Architektur ]
  • [ summarycode : fasst den Scan für erkannte Lizenzen zusammen ]
  • [ Textcode : Führt das Parsen von Text aus ]
  • [ typecode : verarbeitet die Ermittlung des Dateityps ]
  • [ scancode : Befehlszeile und API für Scancode, Kernbestandteil ]

In den Unterabschnitten finden Sie detaillierte Informationen/APIs zu diesen Teilen des Scancode-Toolkit. Die Entwicklungsrichtlinien werden auf einer anderen Seite oder in einem anderen Abschnitt mit kleineren Unterabschnitten angezeigt.

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

Die FAQ-Seite enthält derzeit Fragen, die besser beantwortet werden können und als separate Anleitungen, Tutorials und Referenzdokumente separat strukturiert werden sollten.

  • Wie funktioniert „ScanCode“? Dieses Problem wird in [ 2. Hier finden Sie weitere Erläuterung des Code-Scans ]. Es handelt sich um einen komplett separaten Abschnitt mit viel ausführlicheren Informationen.
  • Wie füge ich neue Lizenzregeln für die erweiterte Erkennung hinzu? Dieses Problem wurde bereits im Abschnitt „Verbesserung der bestehenden Anleitungen“ besprochen. Die Dokumentation wird dorthin verschoben.
  • So fügen Sie eine neue Regel zur Lizenzerkennung hinzu Daraus könnte ein separater Beitrag mit Anleitungen erstellt und weiter ausgearbeitet werden.
  • Erste Schritte bei der Entwicklung Es gibt bereits eine separate Entwicklungsseite und die Informationen überschneiden sich ziemlich stark. Die Umstrukturierung der Entwicklungsseite wurde bereits oben erläutert.
  • Schritte zum Schneiden einer Neuveröffentlichung Dies kann in eine separate Anleitung zum Schneiden einer Neuveröffentlichung umgewandelt werden.
  • Hier finden Sie weitere FAQs, die allgemeine Fragen zum Projekt beantworten und nicht in die Kategorien „Anleitung“/„Tutorial“ fallen.