Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- AboutCode
- Pisarz techniczny:
- ayansinha
- Nazwa projektu:
- Informacje o opcjach wiersza poleceń w narzędziu scancode-narzędzi i zmiana struktury dokumentacji AboutCode na stronie aboutcode.readthedocs.io
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
[ 1. Opcje wiersza poleceń Scancode-Toolkit ]
W wierszu poleceń Scancode-kit znajdziesz szereg opcji, które umożliwiają dostosowanie sposobu skanowania, formatu wyjściowego i kilku innych opcji, takich jak wtyczki post-scan. Obecnie nie ma odpowiedniej dokumentacji, która wyjaśniałaby te opcje, i są dostępne tylko za pomocą flagi „--help” lub „-h”. Celem tego projektu jest stworzenie kompletnej dokumentacji, która wyjaśnia:
[ 1. Wszystkie opcje dostępne w wierszu poleceń ]
- Cel: wyczerpująca lista wszystkich możliwych opcji w wierszu poleceń.
- Omówienie podstawowe: najpierw omówiono domyślne opcje skanowania oraz przykład danych wyjściowych. Krótki opis lub grafika skanowania.
Później to domyślne działanie będzie odnosić się do tego, jak inne opcje zmieniają skanowanie i dane wyjściowe.
Są one omówione szczegółowo i zawierają następujące informacje, jak opisano w kolejnych sekcjach.
[ 2. Rozpocznij strukturę obsługi wersji ]
- Cel: uruchomienie systemu obsługi wersji w celu prawidłowego zachowania opcji dotyczących różnych wersji, interfejsu API i zmian w dokumentacji.
- Problem: obecnie dokumentacja na stronach wiki i ReadTheDokumentacja jest przeznaczona dla starszych wersji i wymaga gruntownej restrukturyzacji.
- Podstawowe informacje: Elementy zestawu narzędzi do skanowania kodu, które zostały zaktualizowane lub mogą zostać zaktualizowane w ramach
- Opcje wiersza poleceń
- Interfejsy API
- Dokumentacja (do zainicjowania) Opcje wiersza poleceń i interfejsy API są zmieniane w poszczególnych wersjach i wersjach. Należy również przestrzegać zapisów z dokumentacji. W przeciwnym razie może to wprowadzać użytkowników w błąd. Narzędzie wiersza poleceń [ --help ] zostało już zaktualizowane pod kątem wszelkich zmian w opcjach i może zostać użyte do odtworzenia obsługi wersji w dokumentacji.
[ 3. Wykorzystanie tych opcji w różnych przypadkach ]
- Cel: ta sekcja zawiera podstawowe informacje o tym, jak wyniki skanowania z zestawu narzędzi skanera mogą być wykorzystane w różnych sytuacjach, a także za pomocą opcji pakietu Scancode-Toolkit, które zapewniają takie funkcje.
- Podstawowe omówienie: w tej sekcji podano różne przykłady scenariuszy użycia oraz podano zalecenia w takich sytuacjach.
- Uwaga: ta część wymaga znaczącej pomocy mentora, jeśli chodzi o dane i wskazówki dotyczące różnych przypadków użycia Scancode-Toolkit.
[ 4. Co zmieniają te opcje na ekranie skanowania i danych wyjściowych?
- Cel: w tej sekcji zawarto podstawowe informacje o tym, jak wyniki skanowania narzędzia scancode- Toolkit można wykorzystywać do różnych celów, a także narzędzia Aboutcode zapewniające takie funkcje.
- Przegląd podstawowy: te opcje zmieniają działanie skanowania. Podstawowy przypadek domyślny zostanie zilustrowany na początku sekcji [ 1. Wszystkie opcje dostępne po kliknięciu Wiersz poleceń ] i w tej sekcji porównamy zmiany wprowadzone przez wszystkie opcje w domyślnym scenariuszu.
[ 5. Formaty wyjściowe i ich przykłady ]
- Cel: w tej sekcji zawarto podstawowe informacje o tym, jak wyniki skanowania narzędzia scancode- Toolkit można wykorzystywać do różnych celów, a także narzędzia Aboutcode zapewniające takie funkcje.
- Omówienie podstawowe: narzędzie Scancode-Tool ma flagi do określania różnych formatów wyjściowych, w których będą generowane wyniki skanowania. Są to:
Ta część będzie dotyczyć - objaśnić szczegółowo formaty wyjściowe
- Podaj przykłady formatów wyjściowych
- podaj inne linki odpowiadające formatowi wyjściowemu i jego użyciu
- sposób przechowywania wyników skanowania w plikach wyjściowych. Prowadzi to również do strony Sposób generowania różnych formatów, co zostanie omówione w sekcji [ 2. Dyskusje na temat skanowania kodu ].
[ 6. Wykorzystanie formatów wyjściowych Scancode w firmach ]
- Cele: wyjaśnienie zastosowań formatów wyjściowych Scancode Na liście pomysłów GSoD oferowane są formaty wyjściowe skanowania. W tej sekcji zastosowano to samo.
- Uwaga: ta część wymaga znaczącej pomocy mentora, jeśli chodzi o dane i wskazówki dotyczące różnych zastosowań biznesowych Scancode-Toolkit.
[ 7. jak te dane wyjściowe są wykorzystywane przez inne projekty AboutCode w celu przeprowadzenia bardziej szczegółowej analizy ]
- Cel: w tej sekcji zawarto podstawowe informacje o tym, jak wyniki skanowania narzędzia scancode- Toolkit można wykorzystywać do różnych celów, a także narzędzia Aboutcode zapewniające takie funkcje.
- Podstawowe informacje:
- Scancode-Workbench Ta część wyjaśnia wizualizację wyników za pomocą aplikacji komputerowej i wskaźników skanowania dokumentacji Workbench, aby uzyskać dodatkową pomoc. W razie potrzeby dodamy wymaganą dokumentację do narzędzia scancode-workbench.
- Deltacode Jak Deltacode pobiera wyniki skanowania do określenia różnic na poziomie plików między dwiema bazami kodu.
[ 2. uporządkowanie struktury dokumentacji AboutCode ]
Ta część zawiera wiele zmian w dokumentacji Aboutcode
[ 1. System obsługi wersji ]
W [ 1. Opcje wiersza poleceń Scancode-Toolkit -> 2. Inicjowanie struktury obsługi wersji]. Omówiliśmy problem z obsługą wersji opcji wiersza poleceń. To samo jest konieczne w innych częściach dokumentacji, które zawierają polecenia lub informacje związane z konkretną wersją, które w przeciwnym razie byłyby niejasne.
[ 2. Ustalanie standardów i testów dokumentacji ]
W dokumentacji znajdują się już testy konstrukcji spinx (tworzy wszystkie strony i sprawdza, czy nie występują błędy składni Sphinx) oraz linki (sprawdza wszystkie linki do innych stron internetowych w dokumentacji) w ramach ciągłej integracji za pomocą Travis-CI. (dodane przeze mnie w tym żądaniu pull nr 17). Teraz potrzebna jest dodatkowa weryfikacja pod kątem konkretnego lintowania w zmienionym tekście i innych standardach. Można to osiągnąć za pomocą restructuredtext-lint, ale wymaga to dalszych badań i zostaną one zrealizowane w ramach mojego projektu GSoD.
[ 3. Dodanie sekcji „Pierwsze kroki” ]
Będzie to sekcja początkowa dla nowych użytkowników i będzie zawierać kompilację najważniejszych i najważniejszych dokumentów, które ułatwią Ci rozpoczęcie pracy z projektami Aboutcode. Każdy projekt Aboutcode będzie miał tę sekcję, w tym Scancode-Toolkit, Scancode-Workbench, Deltacode i inne.
[ 4. Restrukturyzacja zgodnie z 4 funkcjami dokumentu ]
Istniejąca dokumentacja nie jest wyraźnie uporządkowana w ramach 4 funkcji dokumentu: samouczki, instrukcje, odniesienia i wyjaśnienia. Proponuję ich odpowiednią strukturę, dodając więcej informacji, wyjaśnień i wskaźników w razie potrzeby. Dotyczy to wszystkich projektów AboutCode i ich dokumentacji. Poniżej znajdują się 2 przykłady zmian struktury dokumentacji Scancode-Toolkit, które chcę kontynuować w tym projekcie. Podobne zmiany zostaną wprowadzone w pozostałej dokumentacji.
[ 5. Restrukturyzacja strony deweloperskiej (Scancode-Toolkit) ]
Można dodać więcej informacji o kodzie/interfejsach API, aby były bardziej przyjazne dla programistów. Mogą w nim występować linki do [ 2. Dyskusje objaśniające sekcję Skanowanie kodu ] powyżej. Link prowadzi do informacji o działaniu skanowania z kodem używanym do skanowania. Podobnie jak te foldery zawierają różne części narzędzi skanera, ich indywidualne zastosowanie można szczegółowo opisać za pomocą interfejsów API w połączeniu z dyskusją na temat działania skanowania kodu.
- [ cluecode : wtyczki do skanowania licencji, praw autorskich, adresów URL, e-maili ]
- [commoncode : klasa i funkcje pomocnicze]
- [wyodrębnianie kodu : wyodrębnianie różnych formatów archiwum ]
- [ formattedcode : formatowanie wyjściowe dla różnych formatów plików wyjściowych ]
- [Licensecode : kod wykrywania licencji ]
- [ packagedcode : analizowanie różnych formatów pakietów ]
- [ wtyczkakod : klasy dla architektury wtyczek ]
- [podsumowanie kodu : podsumowuje skanowanie w przypadku wykrytych licencji ]
- [ kod tekstowy : obsługuje analizę tekstu ]
- [kod typu : obsługuje określanie typu plików ]
- [ scancode : interfejs wiersza poleceń i interfejs API do skanowania kodu, główna część ]
Ta podsekcja będzie zawierać szczegółowe informacje i interfejsy API na temat tych części zestawu narzędzi skanera. Wskazówki dla programistów będą dostępne na innej stronie lub w innej sekcji mającej mniejsze podsekcje.
[ 6. Zmiana struktury strony z najczęstszymi pytaniami (Scancode-Toolkit) ]
Obecnie strona z najczęstszymi pytaniami zawiera pytania, na które lepiej odpowiedzieć, i powinna zostać uporządkowana jako osobne instrukcje, samouczki i dokumenty referencyjne.
- Jak działa ScanCode? O tym problemie wspomina [ 2. Dyskusje wyjaśniające działanie skanowania kodu ]. Znajdziesz je w osobnej sekcji zawierającej znacznie więcej szczegółów.
- Jak dodać nowe reguły licencji dla ulepszonego wykrywania? Ten problem został już omówiony w sekcji „Ulepszanie instrukcji” – dokumentacja zostanie przeniesiona do tego miejsca.
- Jak dodać nową regułę wykrywania licencji? Tę informację można przygotować osobno w innym poście z instrukcjami.
- Jak zacząć programowanie? Istnieje już osobna strona dla programistów, a informacje w dużej mierze się pokrywają. Przebudowa tej strony została już omówiona.
- Czynności wymagane do wydania nowej wersji Można je przekształcić w osobny poradnik „Jak wyciąć nową wersję”.
- Znajdź odpowiedzi na najczęstsze pytania, które odpowiadają na ogólne pytania dotyczące projektu i nie należą do kategorii „Instrukcje”/„Samouczek”.