Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- AboutCode
- Pisarz techniczny:
- Ayansinha
- Nazwa projektu:
- Informacje o opcjach wiersza poleceń w narzędziu skancodes 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 ]
Scancode-Toolkit zawiera wiele opcji wiersza poleceń, które umożliwiają dostosowanie sposobu skanowania, formatu wyjściowego i kilku innych opcji, np. wtyczek poskanowanych. W przypadku tych opcji nie ma odpowiedniej dokumentacji, która je wyjaśnia, i są dostępne tylko po kliknięciu flagi „--help” lub „-h”. Celem tego projektu jest stworzenie pełnej dokumentacji, która wyjaśni:
[ 1. Wszystkie opcje dostępne z poziomu wiersza poleceń ]
- Cel: pełna lista wszystkich możliwych opcji w wierszu poleceń.
- Omówienie podstawowe: najpierw omówiono domyślne opcje skanowania oraz przykładowe dane wyjściowe. Krótki opis lub schemat skanowania.
Później to domyślne działanie wskazuje, jak inne opcje zmieniają skanowanie i dane wyjściowe.
Zostały one szczegółowo omówione. Zawierają one następujące informacje, o których wspomniano w następnych sekcjach.
[ 2. Rozpocznij strukturę obsługi wersji ]
- Cel: uruchomienie systemu obsługi wersji w celu prawidłowego zachowania opcji obsługi wersji między wersjami, interfejsu API i zmian w dokumentacji.
- Problem: obecnie dokumentacja na stronach wiki oraz ReadTheDoc jest przeznaczona dla starszych wersji i wymaga gruntownej restrukturyzacji.
- Omówienie podstawowe: fragmenty pakietu narzędzi do skanowania kodu, które zostały zaktualizowane lub mogą zostać zaktualizowane w jednej wersji,
- Opcje wiersza poleceń
- Interfejsy API
- Dokumentacja (do zainicjowania) Opcje wiersza poleceń i interfejsy API są zmieniane w różnych wersjach i wersjach. Należy również przestrzegać dokumentacji, ponieważ w przeciwnym razie użytkownicy zaczną wprowadzać w błąd. Narzędzie wiersza poleceń [ --help ] jest już zaktualizowane pod kątem wszelkich zmian w opcjach i może zostać użyte do odtworzenia obsługi wersji podanej w dokumentacji.
[ 3. Jak te opcje można wykorzystać w różnych przypadkach ]
- Cel: ta sekcja zawiera podstawowe podsumowanie dotyczące sposobów wykorzystania wyników skanowania z pakietu narzędzi do skanowania kodu w różnych sytuacjach oraz opcje, które zapewniają taką funkcję.
- Podstawowe omówienie: w tej sekcji przedstawiamy różne przykłady scenariuszy użycia oraz podano opcje zalecane w takich sytuacjach.
- Uwaga: ta część wymaga znaczącej pomocy mentora w kwestii danych wejściowych i wskaźników do różnych przypadków użycia Scancode-Toolkit.
[ 4. Co zmieniają się te opcje w narzędziu do skanowania i danych wyjściowych ]
- Cel: ta sekcja zawiera podstawowe podsumowanie dotyczące sposobów wykorzystania wyników skanowania narzędzia scancode- Toolkit do różnych przyczyn, a także narzędzia Aboutcode zapewniające takie funkcje.
- Przegląd podstawowy: te opcje zmieniają sposób przeprowadzania skanowania. Podstawowy przypadek domyślny zostanie przedstawiony w początkowej sekcji [ 1. Wszystkie opcje dostępne z poziomu wiersza poleceń ] i w tej sekcji pozwalają porównać zmiany wprowadzone przez wszystkie opcje w scenariuszu domyślnym.
[ 5. Formaty wyjściowe i ich przykłady ]
- Cel: ta sekcja zawiera podstawowe podsumowanie dotyczące sposobów wykorzystania wyników skanowania narzędzia scancode- Toolkit do różnych przyczyn, 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 - szczegółowo wyjaśniać 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. Link do informacji o sposobie generowania różnych formatów zostanie omówiony w części [ 2. Dyskusje na temat skanowania kodu ].
[ 6. Wykorzystanie formatów wyjściowych skanowania w firmach ]
- Cele: wyjaśnienie zastosowań formatów wyjściowych Scancode w firmie Na liście pomysłów GSoD wymienione są formaty wyjściowe skanowania. Tak samo wygląda to w tej sekcji.
- Uwaga: ta część wymaga znaczącej pomocy mentora w kwestii danych wejściowych i wskaźników do różnych zastosowań biznesowych Scancode-Toolkit.
[ 7. jak te dane wyjściowe są wykorzystywane przez inne projekty AboutCode w celu bardziej szczegółowej analizy ]
- Cel: ta sekcja zawiera podstawowe podsumowanie dotyczące sposobów wykorzystania wyników skanowania narzędzia scancode- Toolkit do różnych przyczyn, a także narzędzia Aboutcode zapewniające takie funkcje.
- Podstawowe informacje:
- Scancode-Workbench W tej części wyjaśniamy wizualizowanie wyników za pomocą aplikacji komputerowej oraz wskaźniki do dokumentacji scancode-workbench, która zapewnia dodatkową pomoc. W razie potrzeby dodamy do pliku scancode-workbench wymaganą dokumentację.
- Sposób pobierania wyników kodu skanowania przez Deltacode w celu określenia różnic na poziomie plików między 2 bazami kodu.
[ 2. Ponownie uporządkuj strukturę 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ówiono problem z obsługą wersji opcji wiersza poleceń. To samo dotyczy innych części dokumentacji, które zawierają polecenia lub informacje związane z konkretną wersją, które w innym przypadku mogłyby wprowadzać w błąd.
[ 2. Ustawianie dokumentacji standardów i testów ]
Dokumentacja zawiera już testy pod kątem tworzenia spinx (składa wszystkie strony i sprawdza, czy nie zawierają błędów składni Sphinx) oraz linki (sprawdza wszystkie linki do innych stron internetowych w dokumentacji) z funkcją ciągłej integracji poprzez Travis-CI. (Dodane przeze mnie w tym żądaniu pull nr 17) Teraz potrzebne jest więcej kontroli pod kątem określonych lintowania w przestrukturze tekstu i innych standardach. Można to osiągnąć za pomocą restructuredtext-lint, ale wymaga to dalszych badań, które zostaną wprowadzone 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 ułatwiających rozpoczęcie pracy z projektami Aboutcode. Każdy projekt Aboutcode będzie zawierał tę sekcję, w tym Scancode-Toolkit, Scancode-Workbench, Deltacode i inne.
[ 4. Zmiana struktury zgodnie z 4 funkcjami dokumentu ]
Istniejąca dokumentacja nie jest wyraźnie uporządkowana w ramach 4 funkcji dokumentu – samouczków, instrukcji, materiałów referencyjnych i wyjaśnień. Proponuję uporządkować je w odpowiedni sposób, dodając w razie potrzeby więcej informacji, wyjaśnień lub wskaźników. Dotyczy to wszystkich projektów AboutCode i ich dokumentacji. Poniżej znajdują się 2 przykłady proponowanej przeze mnie zmiany struktury dokumentacji Scancode-Toolkit, którą chcę kontynuować w tym projekcie. Podobne zmiany zostaną wprowadzone w pozostałej dokumentacji.
[ 5. Restrukturyzacja strony dla programistów (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. Zawiera on link do opisu działania skanowania z kodem używanym do skanowania. Podobnie jak te foldery zawierają różne części zestawu narzędzi do skanowania kodu, ich indywidualne zastosowanie można omówić z interfejsami API w połączeniu z dyskusją na temat działania skanowania kodu.
- [ cluecode : wtyczki do skanowania licencji, prawa autorskie, adresy url, e-maile ]
- [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 ]
- [ kod wtyczki : klasy dla architektury wtyczek ]
- [podsumowanie kodu : zawiera podsumowanie skanowania w przypadku wykrytych licencji ]
- [ kod tekstowy : obsługuje analizę tekstu ]
- [ kod typu : obsługuje określanie typu plików ]
- [ skanowanie kodu : interfejs wiersza poleceń i interfejs API do skanowania kodu, główna część ]
Ta podsekcja będzie zawierać szczegółowe informacje i interfejsy API dotyczące tych części zestawu narzędzi do skanowania kodu. Wskazówki dla programistów znajdziesz na innej stronie lub w innej sekcji z mniejszymi podsekcjami.
[ 6. Zmiana struktury strony z najczęstszymi pytaniami (Scancode-Toolkit) ]
Obecnie strona z najczęstszymi pytaniami, na które łatwiej odpowiedzieć, jest dostępna i powinna być podzielona na osobne instrukcje, samouczki i dokumenty referencyjne.
- Jak działa ScanCode? Ten problem jest opisany w [ 2. Dyskusje wyjaśniające, czym jest Skanowanie kodu ]. Znajdziesz je w osobnej sekcji, zawierającej więcej szczegółów.
- Jak dodać nowe reguły dotyczące licencji, aby poprawić wykrywanie? Ten problem został już omówiony w sekcji dotyczącej ulepszania istniejących instrukcji. Dokumentacja zostanie przeniesiona do tego miejsca.
- Jak dodać nową regułę wykrywania licencji? Można je rozwinąć w innym poście z instrukcjami, które można rozwinąć.
- Jak zacząć programowanie? Istnieje już osobna strona deweloperska, a informacje w dużym stopniu się pokrywają. Zmiana struktury strony tworzenia została już omówiona.
- Czynności, które należy wykonać, aby wyciąć nowe wydanie, możesz je przekształcić w osobny poradnik.
- Znajdź więcej najczęstszych pytań, które odpowiadają na ogólne pytania dotyczące projektu i nie należą do kategorii „Instrukcje” ani „Samouczek”.