Informationen zum Projekt Code

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:
AboutCode
Technischer Redakteur:
Ayansinha
Projektname:
Unter „aboutcode.readthedocs.io“ finden Sie weitere Informationen zu den Befehlszeilenoptionen im scancode-Toolkit und in der „AboutCode“-Dokumentation neu strukturieren (in englischer Sprache).
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

[ 1. Scancode-Toolkit-Befehlszeilenoptionen ]

Scancode-Toolkit verfügt über eine Vielzahl von Befehlszeilenoptionen, mit denen Sie die Durchführung des Scans, das Ausgabeformat und verschiedene weitere Optionen wie Plug-ins für den Post-Scan anpassen können. Für diese Optionen gibt es derzeit keine entsprechende Erklärung. Sie sind nur über das Flag „--help“ oder „-h“ verfügbar. Dieses Projekt zielt auf die Erstellung einer vollständigen Dokumentation ab, die Folgendes erklärt:

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

  • Ziel: Eine umfassende Liste aller möglichen Optionen über die Befehlszeile.
  • Grundlegende Übersicht: Zunächst werden die Standardscanoptionen anhand eines Beispiels für die Ausgabe erläutert. Eine kurze Grafik/Beschreibung zur Durchführung des Scans.
    Im Folgenden verweist dieses Standardverhalten darauf, wie die anderen Optionen den Scan und die Ausgabe ändern.
    Diese Punkte werden nun ausführlich besprochen. Sie enthalten die folgenden Informationen, die in den nächsten Abschnitten erläutert werden.

[ 2. Versionierungsstruktur initiieren ]

  • Ziel: Einführung eines Versionsverwaltungssystems, um veröffentlichungsübergreifende Optionen bzw. API- und Dokumentationsänderungen ordnungsgemäß zu verwalten.
  • Problem: Derzeit bezieht sich die Dokumentation im Wiki und auf den ReadTheDocs-Seiten auf ältere Versionen und muss grundlegend umstrukturiert werden.
  • Allgemeine Übersicht: Die Teile des Scancode-Toolkits, die in der Version aktualisiert wurden bzw. aktualisiert werden könnten,
  • Befehlszeilenoptionen
  • APIs
  • Dokumentation (noch zu initiieren) Die Befehlszeilenoptionen und die APIs werden in Versionen und Releases geändert. Auch die Dokumentation muss eingehalten werden, da dies andernfalls zu einer enormen Verwirrung bei den Nutzern führt. Das Befehlszeilen-Dienstprogramm [ --help ] wird bereits für eventuelle Ä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-Toolkit für verschiedene Zwecke verwendet werden können und welche Scancode-Toolkit-Optionen diese Funktionen bieten.
  • Allgemeiner Überblick: In diesem Abschnitt werden verschiedene Beispiele für Anwendungsfälle beschrieben und Sie erfahren, welche Optionen in diesen Szenarien empfohlen werden.
  • Hinweis: Dieser Teil erfordert viel Unterstützung von der beratenden Person in Bezug auf Eingaben und Verweise auf verschiedene Anwendungsfälle im Scancode-Toolkit.

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

  • Ziel: In diesem Abschnitt erhalten Sie eine grundlegende Zusammenfassung darüber, wie die Scanergebnisse des Scancode-Toolkit für verschiedene Zwecke verwendet werden können, sowie zu den Infocode-Tools, die diese Funktionen bieten.
  • Grundlegende Übersicht: Die Optionen ändern die Funktionsweise des Scans. Ein einfacher Standardfall wird am Anfang des Abschnitts [ 1. Alle über die Befehlszeile ] verfügbaren Optionen und in diesem Abschnitt werden die Änderungen verglichen, die alle Optionen in diesem Standardszenario mit sich bringen.

[ 5. Ausgabeformate und ihre Beispiele ]

  • Ziel: In diesem Abschnitt erhalten Sie eine grundlegende Zusammenfassung darüber, wie die Scanergebnisse des Scancode-Toolkit für verschiedene Zwecke verwendet werden können, sowie zu den Infocode-Tools, die diese Funktionen bieten.
  • Grundlegende Übersicht: Das Scancode-Tool verfügt über Flags, mit denen Sie verschiedene Ausgabeformate festlegen können, in denen die Scan-Ergebnisse generiert werden. Diese sind:
    In diesem Teil
  • im Detail die Ausgabeformate
  • geben Beispiele zu den Ausgabeformaten an,
  • Geben Sie weitere Links zu dem Ausgabeformat und seiner Verwendung an.
  • wie Scanergebnisse in den Ausgabedateien gespeichert werden. Hier finden Sie auch einen Link zur Generierung der verschiedenen Formate, die unter [ 2. Diskussionen zur Erläuterung des Codescans ].

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

  • Ziele: Die geschäftlichen Anwendungsfälle von Scancode-Ausgabeformaten erklären In der GSoD-Ideenliste wird Scancode-Ausgabeformate als Referenzidee erwähnt. In diesem Abschnitt wird das Gleiche implementiert.
  • Hinweis: Dieser Teil erfordert viel Unterstützung vom Mentor, wenn es um Beiträge zu verschiedenen geschäftlichen Anwendungsfällen des Scancode-Toolkits geht.

[ 7. Wie diese Ausgaben von anderen AboutCode-Projekten zur weiteren Analyse verwendet werden ]

  • Ziel: In diesem Abschnitt erhalten Sie eine grundlegende Zusammenfassung darüber, wie die Scanergebnisse des Scancode-Toolkit für verschiedene Zwecke verwendet werden können, sowie zu den Infocode-Tools, die diese Funktionen bieten.
  • 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. Falls erforderlich, wird die erforderliche Dokumentation zu scancode-workbench hinzugefügt.
  • Deltacode Wie Scancodeergebnisse von Deltacode verwendet werden, um Unterschiede auf Dateiebene zwischen zwei Codebasen zu ermitteln.

[ 2. Struktur der AboutCode-Dokumentation neu organisieren ]

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

[ 1. Versionsverwaltungssystem ]

In [ 1. Scancode-Toolkit-Befehlszeilenoptionen -> 2. Initiate Versioning Structure] wird das Problem der Versionsverwaltung der Befehlszeilenoptionen 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-Elemente in 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. Abschnitt „Erste Schritte“ hinzufügen ]

Dieser Abschnitt dient Neueinsteigern als Einstieg. Er enthält eine Zusammenstellung der grundlegendsten und wichtigsten Dokumente für den Einstieg in Aboutcode-Projekte. Jedes Aboutcode-Projekt enthält diesen Abschnitt, einschließlich Scancode-Toolkit, Scancode-Workbench, Deltacode und weiteren.

[ 4. Umstrukturierung gemäß den 4 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 bei Bedarf weitere Informationen/Erläuterungen/Hinweise hinzuzufügen. Dies 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 vorgeschlagen habe und die ich in diesem Projekt weiterführen möchte. Für den Rest der Dokumentation werden ähnliche Änderungen vorgenommen.

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

Für eine entwicklerfreundlichere Gestaltung können weitere Informationen zum Code/APIs hinzugefügt werden. Links zu den [ 2. Diskussionen zur Erläuterung des obigen Abschnitts „Codescans“. Dadurch wird die Funktionsweise des Scans mit dem Code verknüpft, der zum Ausführen des Scans verwendet wird. Ähnlich wie diese Ordner verschiedene Teile des Scancode-Toolkits enthalten, kann deren individuelle Verwendung mithilfe der APIs ausgearbeitet werden. Im Anschluss wird die Funktionsweise von Scancode erläutert.

  • [ cuecode : Plug-ins zum Scannen von Lizenzen, Urheberrechten, URLs, E-Mails ]
  • [ Commoncode : Hilfsklassen und Funktionen]
  • [Extractcode : Extrahiert verschiedene Archivformate ]
  • [ formattedcode : Ausgabeformatierung für verschiedene Ausgabedateiformate ]
  • [ lizenzierter Code : 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 Parsing des Textes durch ]
  • [ typecode : übernimmt Dateitypbestimmung ]
  • [ scancode : CLI und API zum Scannen des Codes, Hauptbestandteil ]

In den Unterabschnitten dieses Unterabschnitts 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. FAQ-Seite neu strukturieren (Scancode-Toolkit) ]

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

  • Wie funktioniert ScanCode? Dieses Problem wird in [ 2. Diskussionen, in denen das Scannen von Code erläutert wird.
  • 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 einer Anleitung erstellt werden, der in weiteren Ausführungen ergänzt werden könnte.
  • Erste Schritte mit der Entwicklung Es gibt bereits eine separate Entwicklungsseite und die Informationen überschneiden sich ziemlich stark. Die Umstrukturierung der Entwicklungsseite wurde bereits oben erwähnt.
  • Schritte zum Schneiden einer Neuveröffentlichung Dies kann in eine separate Anleitung umgewandelt werden.
  • Suchen Sie weitere FAQ-Fragen, die allgemeine Fragen zum Projekt beantworten und nicht in die Kategorien „Anleitung“/„Tutorial“ fallen.