Diese Seite enthält die Details eines Projekts zum technischen Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- AboutCode
- Technischer Autor:
- ayansinha
- Projektname:
- Referenz für Befehlszeilenoptionen in scancode-toolkit und Neustrukturierung der AboutCode-Dokumentation unter aboutcode.readthedocs.io
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
[ 1. Befehlszeilenoptionen für Scancode-Toolkit ]
Scancode-Toolkit bietet eine Vielzahl von Befehlszeilenoptionen, mit denen Sie anpassen können, wie der Scan ausgeführt wird, das Ausgabeformat und verschiedene andere Optionen wie Plug‑ins nach dem Scan. Für diese Optionen gibt es derzeit keine ordnungsgemäße Dokumentation, in der sie erklärt werden. Sie sind nur über das Flag „--help“ oder „-h“ verfügbar. Ziel dieses Projekts ist es, eine vollständige Dokumentation zu erstellen, in der Folgendes erklärt wird:
[ 1. Alle über die Befehlszeile verfügbaren Optionen ]
- Ziel: Eine umfassende Liste aller möglichen Optionen über die Befehlszeile.
- Grundlegende Übersicht: Zuerst werden die Standardoptionen für den Scan mit einem Beispiel für die Ausgabe erläutert. Eine kurze Grafik/Beschreibung, wie der Scan ausgeführt wird.
Danach dient dieses Standardverhalten als Referenz dafür, wie die anderen Optionen den Scan und die Ausgabe verändern.
Diese werden im Detail erläutert und enthalten die in den nächsten Abschnitten genannten Informationen.
[ 2. Versionsverwaltungssystem initiieren ]
- Ziel: Ein Versionsverwaltungssystem initiieren, um Optionen/APIs und Dokumentationsänderungen für verschiedene Releases ordnungsgemäß zu verwalten.
- Problem: Die Dokumentation im Wiki und auf den ReadTheDocs-Seiten bezieht sich auf ältere Releases und muss grundlegend neu strukturiert werden.
- Grundlegende Übersicht: Die Teile des Scancode-Toolkits, die in der Version aktualisiert wurden/werden könnten, sind
- Befehlszeilenoptionen
- APIs
- Dokumentation (wird initiiert): Die Befehlszeilenoptionen und die APIs werden in Versionen und Releases geändert. Die Dokumentation muss ebenfalls angepasst werden, da sonst bei den Nutzern große Verwirrung entstehen kann. Das Befehlszeilenprogramm [ --help ] wurde bereits für alle Änderungen an den Optionen aktualisiert und könnte verwendet werden, um die Versionsverwaltung in der Dokumentation zu replizieren.
[ 3. Verwendung dieser Optionen in verschiedenen Fällen ]
- Ziel: In diesem Abschnitt wird eine grundlegende Zusammenfassung der verschiedenen Möglichkeiten zur Verwendung der Scanergebnisse des Scancode-Toolkits und der Scancode-Toolkit-Optionen, die diese Funktionalität bieten, gegeben.
- Grundlegende Übersicht: In diesem Abschnitt werden verschiedene Anwendungsfallszenarien und die in diesen Szenarien empfohlenen Optionen beschrieben.
- Hinweis: Für diesen Teil ist erhebliche Unterstützung durch den Mentor in Form von Eingaben und Hinweisen zu verschiedenen Anwendungsfällen des Scancode-Toolkits erforderlich.
[ 4. Änderungen durch diese Optionen im Scan und in der Ausgabe ]
- Ziel: In diesem Abschnitt wird eine grundlegende Zusammenfassung der verschiedenen Möglichkeiten zur Verwendung der Scanergebnisse des Scancode-Toolkits und der AboutCode-Tools, die diese Funktionalität bieten, gegeben.
- Grundlegende Übersicht: Die Optionen ändern das Verhalten des Scans. Ein grundlegender Standardfall wird im ersten Abschnitt [ 1. Alle über die Befehlszeile verfügbaren Optionen ] veranschaulicht. In diesem Abschnitt werden die Änderungen verglichen, die alle Optionen an diesem Standardszenario vornehmen.
[ 5. Ausgabeformate und Beispiele dafür ]
- Ziel: In diesem Abschnitt wird eine grundlegende Zusammenfassung der verschiedenen Möglichkeiten zur Verwendung der Scanergebnisse des Scancode-Toolkits und der AboutCode-Tools, die diese Funktionalität bieten, gegeben.
- Grundlegende Übersicht: Das Scancode-Tool bietet Flags, mit denen Sie verschiedene Ausgabeformate angeben können, in denen die Scanergebnisse generiert werden. Diese sind -
In diesem Teil wird - das Ausgabeformat im Detail erklärt
- Beispiele für das Ausgabeformat gegeben
- weitere Links zum Ausgabeformat und seiner Verwendung gegeben
- erklärt, wie Scanergebnisse in den Ausgabedateien gespeichert werden. Außerdem wird auf den Abschnitt „So werden diese verschiedenen Formate generiert“ verlinkt, der in [ 2. Diskussionen zur Codeüberprüfung ] erläutert wird.
[ 6. Geschäftliche Nutzung von Scancode-Ausgabeformaten ]
- Ziele: Geschäftliche Anwendungsfälle von Scancode-Ausgabeformaten erläutern. In der Liste der GSoD-Ideen werden Scancode-Ausgabeformate als Referenzidee genannt. Dieser Abschnitt implementiert dies.
- Hinweis: Für diesen Teil ist erhebliche Unterstützung durch den Mentor in Form von Eingaben und Hinweisen zu verschiedenen geschäftlichen Anwendungsfällen des Scancode-Toolkits erforderlich.
[ 7. Verwendung dieser Ausgaben durch andere AboutCode-Projekte für weitere Analysen ]
- Ziel: In diesem Abschnitt wird eine grundlegende Zusammenfassung der verschiedenen Möglichkeiten zur Verwendung der Scanergebnisse des Scancode-Toolkits und der AboutCode-Tools, die diese Funktionalität bieten, gegeben.
- Grundlegende Übersicht:
- Scancode-Workbench: In diesem Teil wird die Visualisierung von Ergebnissen mit der Desktop-App erläutert. Außerdem werden Links zur Scancode-Workbench-Dokumentation für weitere Unterstützung angegeben. Bei Bedarf wird die erforderliche Dokumentation zur Scancode-Workbench hinzugefügt.
- Deltacode: Hier wird erläutert, wie Scancode-Ergebnisse von Deltacode verwendet werden, um Unterschiede auf Dateiebene zwischen zwei Codebasen zu ermitteln.
[ 2. Neustrukturierung der AboutCode-Dokumentation ]
Dieser Teil enthält eine Reihe von Änderungen an der AboutCode-Dokumentation.
[ 1. Versionsverwaltungssystem ]
In [ 1. Befehlszeilenoptionen für Scancode-Toolkit -> 2. Versionsverwaltungssystem initiieren] wird das Problem der Versionsverwaltung der Befehlszeilenoptionen erwähnt. Dasselbe ist auch für andere Teile der Dokumentation erforderlich, die versionsspezifische Befehle/Informationen enthalten, die sonst zu Verwirrung führen könnten.
[ 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 die Linkprüfung (prüft alle Links zu anderen Webseiten in der Dokumentation) mit Continuous Integration über Travis-CI. (Von mir in dieser Pull-Anfrage #17 hinzugefügt) Jetzt sind weitere Prüfungen für spezifisches Linting in reStructured Text und andere 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 Einstieg für Neulinge und 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 anderer.
[ 4. Neustrukturierung gemäß den vier Dokumentfunktionen ]
Die vorhandene Dokumentation ist nicht explizit in die vier Dokumentfunktionen unterteilt: Tutorials, Anleitungen, Referenz und Erklärungen. Ich schlage vor, sie entsprechend zu strukturieren und bei Bedarf weitere Informationen/Erklärungen/Hinweise hinzuzufügen. Dies gilt für alle AboutCode-Projekte und ihre Dokumentation. Unten finden Sie zwei Beispiele für die von mir vorgeschlagene Neustrukturierung der Scancode-Toolkit-Dokumentation, die ich in diesem Projekt umsetzen möchte. Ähnliche Änderungen werden an der übrigen Dokumentation vorgenommen.
[ 5. Neustrukturierung der Entwicklungsseite (Scancode-Toolkit) ]
Es könnten weitere Informationen zum Code/zu den APIs hinzugefügt werden, um die Seite entwicklerfreundlicher zu gestalten. Es können Links zum Abschnitt [ 2. Diskussionen zur Codeüberprüfung ] oben eingefügt werden. Dadurch wird die Erklärung der Funktionsweise des Scans mit dem Code verknüpft, der zum Ausführen 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 Scancode erläutert werden.
- [ cluecode : Plug‑ins zum Scannen von Lizenzen, Urheberrechten, URLs und E‑Mail-Adressen ]
- [ commoncode : Hilfsklassen und -funktionen]
- [ extractcode : Extrahiert verschiedene Archivformate ]
- [ formattedcode : Ausgabeformatierung für verschiedene Ausgabedateiformate ]
- [ licensedcode : Code zur Lizenzerkennung ]
- [ packagedcode : Parsen verschiedener Paketformate ]
- [ plugincode : Klassen für die Plug‑in-Architektur ]
- [ summarycode : Zusammenfassung des Scans zu erkannten Lizenzen ]
- [ textcode : Verarbeitet das Parsen von Text ]
- [ typecode : Verarbeitet die Bestimmung des Dateityps ]
- [ scancode : Befehlszeile und API für Scancode, den Kernteil ]
Dieser Unterabschnitt enthält detaillierte Informationen/APIs zu diesen Teilen des Scancode-Toolkits in entsprechenden Unterunterabschnitten. Die Entwicklungsrichtlinien befinden sich auf einer anderen Seite oder in einem anderen Abschnitt mit kleineren Unterabschnitten.
[ 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 strukturiert werden sollten.
- Wie funktioniert ScanCode? Dieses Problem wird in [ 2. Diskussionen zur Codeüberprüfung ] behandelt und wird ein völlig separater Abschnitt mit viel mehr Details.
- Wie füge ich neue Lizenzregeln für eine verbesserte Erkennung hinzu? Dieses Problem wurde bereits zuvor unter „Vorhandene Anleitungen verbessern“ behandelt. Die Dokumentation wird dorthin verschoben.
- Wie füge ich eine neue Lizenzerkennungsregel hinzu? Daraus könnte ein separater Beitrag mit der Anleitung „Wie füge ich eine neue Lizenzerkennungsregel hinzu?“ erstellt werden, der ausführlicher ist.
- Wie fange ich mit der Entwicklung an? Es gibt bereits eine separate Entwicklungsseite und die Informationen überschneiden sich stark. Die Neustrukturierung der Entwicklungsseite wurde bereits oben behandelt.
- Schritte zum Erstellen einer Neuveröffentlichung: Dies kann in eine separate Anleitung „So erstellen Sie eine Neuveröffentlichung“ umgewandelt werden.
- Weitere FAQ-Fragen finden, die allgemeine Fragen zum Projekt beantworten und nicht in die Kategorien „Anleitung“/„Tutorial“ fallen.