Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- AboutCode
- Pisarz techniczny:
- ayansinha
- Nazwa projektu:
- Zapoznaj się z informacjami o opcjach wiersza poleceń w skancode- Toolkit i na stronie aboutcode.readthedocs.io oraz reorganizację struktury dokumentacji Informacje o kodzie.
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
[ 1. Opcje wiersza poleceń narzędzia Scancode-Toolkit
Zestaw Scancode-Toolkit zawiera wiele opcji wiersza poleceń, które pozwalają dostosować sposób skanowania, format wyjściowy i kilka innych opcji, np. wtyczki postskanowe. Te opcje nie są obecnie odpowiednio opisane w dokumentacji i są dostępne tylko za pomocą parametru „--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 dostępnych opcji w wierszu poleceń.
- Podstawowe omówienie: najpierw omówimy domyślne opcje skanowania wraz z przykładem ich wyników. Krótka grafika lub opis sposobu przeprowadzania skanowania.
W dalszej części tego artykułu to domyślne działanie będzie służyć jako punkt odniesienia do tego, jak inne opcje zmieniają skanowanie i wyjście.
Zostały one szczegółowo omówione i zawierają poniższe informacje, jak opisano w kolejnych sekcjach.
[ 2. Inicjowanie struktury wersji
- Cel: inicjowanie systemu wersji w celu prawidłowego zarządzania opcjami w różnych wersjach, interfejsami API i zmianami w dokumentacji.
- Problem: obecna dokumentacja w wiki i na stronach ReadTheDocs dotyczy starszych wersji i wymaga gruntownej przebudowy.
- Podstawowe omówienie: Niektóre z aktualizacji zestawu narzędzi Scancode- Toolkit, które można zaktualizować w wersji,
- Opcje wiersza poleceń
- Interfejsy API
- Dokumentacja (do zainicjowania)Opcje wiersza poleceń i interfejsy API zmieniają się w wersjach i wydańach, dlatego dokumentacja musi być aktualizowana wraz z nimi, aby nie wprowadzać użytkowników w błąd. Narzędzie wiersza poleceń [ --help ] jest już zaktualizowane o wszelkie zmiany w opcjach i można go użyć do powielenia wersji w dokumentacji.
[ 3. Jak te opcje można stosować w różnych przypadkach
- Cel: w tej sekcji znajdziesz podstawowe omówienie sposobów wykorzystywania wyników skanowania w różnych przypadkach oraz opcji narzędzia scancode-toolkit, które umożliwiają takie działanie.
- Podstawowe omówienie: w tej sekcji znajdziesz przykłady scenariuszy użycia oraz opcje zalecane w tych sytuacjach.
- Uwaga: ta część wymaga znacznej pomocy mentora w zakresie informacji i wskazówek dotyczących różnych zastosowań narzędzia Scancode-Toolkit.
[ 4. Jak te opcje wpływają na skanowanie i wyjście
- Cel: w tej sekcji znajdziesz podstawowe omówienie sposobów wykorzystania wyników skanowania w narzędziach scancode-toolkit w różnych przypadkach oraz narzędzi Aboutcode, które zapewniają taką funkcjonalność.
- Podstawowy przegląd: opcje te zmieniają sposób przeprowadzania skanowania. W sekcji początkowej [ 1. W tej sekcji znajdziesz wszystkie opcje dostępne w wierszu polecenia. Porównamy w niej zmiany, jakie w tym domyślnym scenariuszu wprowadzą poszczególne opcje.
[ 5. Formaty danych wyjściowych i ich przykłady
- Cel: w tej sekcji znajdziesz podstawowe omówienie sposobów wykorzystania wyników skanowania w narzędziach scancode-toolkit w różnych przypadkach oraz narzędzi Aboutcode, które zapewniają taką funkcjonalność.
- Podstawowy przegląd: narzędzie Scancode-Tool zawiera flagi, które umożliwiają określenie różnych formatów wyjściowych, w których będą generowane wyniki skanowania. Są to -
Ta część - szczegółowo wyjaśnić formaty wyjściowe;
- podać przykłady formatów wyjściowych.
- podaj inne linki odpowiadające formatowi wyjściowemu i jego zastosowaniu;
- jak wyniki skanowania są przechowywane w plikach wyjściowych. Link ten prowadzi też do opisu sposobu generowania tych różnych formatów, który znajdziesz w sekcji [ 2. Dyskusje wyjaśniające skanowanie kodu ].
[ 6. Zastosowanie w firmie formatów wyjściowych kodu skanowania ]
- Cele: wyjaśnij zastosowania biznesowe formatów danych wyjściowych kodu skanowania. Na liście pomysłów na potrzeby GSoD formaty danych wyjściowych kodu skanowania są wymienione jako pomysł referencyjny. To samo dotyczy tej sekcji.
- Uwaga: ta część wymaga znacznej pomocy mentora w zakresie informacji i wskazówek dotyczących różnych zastosowań biznesowych narzędzia Scancode-Toolkit.
[ 7. Jak te dane wyjściowe są używane przez inne projekty AboutCode do dalszej analizy ]
- Cel: w tej sekcji znajdziesz podstawowe omówienie sposobów wykorzystania wyników skanowania w narzędziach scancode-toolkit w różnych przypadkach oraz narzędzi Aboutcode, które zapewniają taką funkcjonalność.
- Podstawowe informacje:
- Scancode-Workbench W tej części omawiamy wizualizację wyników w aplikacji komputerowej oraz wskaźniki do skanowania dokumentacji panelu roboczego w celu uzyskania większej pomocy w tym zakresie. W razie potrzeby doda wymaganą dokumentację do scancode-workbench.
- Kodowanie Deltacode Jak Deltacode pobiera wyniki skanowania kodu w celu określenia różnic w poziomie plików między 2 bazami kodu.
[ 2. Zmiana struktury dokumentacji AboutCode
Ta część zawiera wiele zmian w dokumentacji dotyczącej Aboutcode.
[ 1. System obsługi wersji ]
W [1. Opcje wiersza poleceń Scancode-Toolkit -> 2. Inicjuj strukturę obsługi wersji], wspomniano o problemie z obsługą wersji opcji wiersza poleceń. To samo dotyczy innych części dokumentacji, które zawierają polecenia lub informacje dotyczące konkretnej wersji, które w przeciwnym razie mogłyby wprowadzać w błąd.
[ 2. wyznaczanie standardów i testów dokumentacji ]
Dokumentacja zawiera już testy dla spinx-build (tworzy wszystkie strony i sprawdza błędy składni Sphinxa) oraz link check (sprawdza wszystkie linki do innych stron internetowych z dokumentacji) z ciągłą integracją za pomocą Travis-CI. (dodano przeze mnie w Pull Request #17) Teraz potrzebuje więcej kontroli w zakresie sprawdzania błędów w reStructured Text i innych standardach. Można to osiągnąć za pomocą narzędzia restructuredtext-lint, ale wymaga to dalszych badań i zostanie zrobione w ramach projektu GSoD.
[ 3. Dodawanie 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 Informationcode będzie zawierać tę sekcję, w tym Scancode-Toolkit, Scancode-Workbench, Deltacode i inne.
[ 4. Zmiana struktury zgodnie z 4 funkcjami dokumentu
Obecna dokumentacja nie jest wyraźnie uporządkowana według 4 funkcji dokumentu: samouczków, instrukcji, podręczników i wyjaśnień. Proponuję uporządkowanie tych informacji, dodanie dodatkowych informacji lub wyjaśnień. Dotyczy to wszystkich projektów AboutCode i ich dokumentacji. Poniżej znajdziesz 2 przykłady restrukturyzacji dokumentacji narzędzia Scancode, które proponuję i które chciałbym wprowadzić w tym projekcie. Podobne zmiany zostaną wprowadzone w pozostałych dokumentach.
[ 5. Zmiana struktury strony programowania (Scancode-Toolkit) ]
Aby ułatwić deweloperom korzystanie z dokumentacji, można dodać do niej więcej informacji o kodzie i interfejsach API. Mogą się w nim znajdować linki do [ 2. Dyskusje wyjaśniające sekcję „Skanowanie kodu” powyżej. To łączy wyjaśnienie działania skanowania z kodem, którego używa do jego wykonania. Ponieważ te foldery zawierają różne części pakietu narzędzi scancode, ich indywidualne użycie można opracować za pomocą interfejsów API w związku z dyskusją na temat działania narzędzia scancode.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : extracts different archive formats ]
- [ formattedcode : output formatting for different output file formats ]
- [ licencjonowany kod : kod wykrywania licencji ]
- [ kod_pakietowy : analiza różnych formatów pakietów ]
- [ Plugincode : klasy dla architektury wtyczek ]
- [ kod podsumowania : podsumowuje skanowanie w przypadku wykrytych licencji ]
- [ textcode : handles text parsing ]
- [ typecode : handles file type determinations ]
- [ scancode : CLI and API to scancode, the core part ]
Ta podsekcja zawiera szczegółowe informacje/interfejsy API dotyczące tych części zestawu narzędzi Scancode- Toolkit w odpowiednich podsekcjach. Wytyczne dotyczące rozwoju znajdziesz na innej stronie lub w innej sekcji zawierającej mniejsze podsekcje.
[ 6. Restrukturyzacja strony z najczęstszymi pytaniami (Scancode-Toolkit)
Obecna strona z najczęstszymi pytaniami zawiera pytania, na które można udzielić lepszych odpowiedzi. Należy ją uporządkować, tworząc oddzielne dokumenty instruktażowe, samouczki i dokumenty referencyjne.
- Jak działa ScanCode? Ten problem jest omawiany w sekcji [ 2. Dyskusje wyjaśniające skanowanie kodu ] będą stanowiły osobną sekcję z wiele więcej szczegółów.
- Jak dodać nowe reguły licencji na potrzeby funkcji Enhanced Detection? Ten problem został już omówiony w artykule „Ulepszanie istniejących instrukcji”. Dokumentacja zostanie tam przeniesiona.
- Jak dodać nową regułę wykrywania licencji? Informacje na ten temat można rozwinąć w innym poście z instrukcjami i podać więcej szczegółów.
- Jak zacząć korzystać z rozwoju? Istnieje już osobna strona deweloperów, a informacje się dość mocno pokrywają. Powyżej omówiliśmy już kwestię restrukturyzacji strony deweloperskiej.
- Kroki do wykonania nowego wydania. Można go przekształcić w osobny artykuł „Jak wykonać nowe wydanie”.
- Znajdź więcej często zadawanych pytań, które odpowiadają na ogólne pytania dotyczące projektu i nie pasują do kategorii „Jak to zrobić” lub „Samouczek”.