Ta strona zawiera szczegóły projektu dotyczącego przygotowywania tekstów technicznych, który został przyjęty do programu Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- AboutCode
- Pisarz techniczny:
- ayansinha
- Nazwa projektu:
- Reference for Command Line Options in scancode-toolkit and Reorganize the structure of AboutCode documentation at aboutcode.readthedocs.io
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
[ 1. Opcje wiersza poleceń w scancode-toolkit ]
Scancode-Toolkit ma wiele opcji wiersza poleceń, które pozwalają dostosować sposób przeprowadzania skanowania, format wyjściowy i inne opcje, takie jak wtyczki po skanowaniu. Te opcje nie mają obecnie odpowiedniej dokumentacji, która by je wyjaśniała, i są dostępne tylko za pomocą flagi „--help” lub „-h”. Celem tego projektu jest stworzenie pełnej dokumentacji, która wyjaśnia:
[ 1. Wszystkie opcje dostępne w wierszu poleceń ]
- Cel: wyczerpująca lista wszystkich możliwych opcji w wierszu poleceń.
- Podstawowe informacje: najpierw omawiane są domyślne opcje skanowania wraz z przykładem danych wyjściowych. Krótka grafika lub opis sposobu przeprowadzania skanowania.
Od tego momentu to domyślne zachowanie będzie służyć jako odniesienie do tego, jak inne opcje zmieniają skanowanie i dane wyjściowe.
Te opcje zostaną omówione szczegółowo i będą zawierać informacje wymienione w kolejnych sekcjach.
[ 2. Wprowadzenie struktury obsługi wersji ]
- Cel: wprowadzenie systemu obsługi wersji, który pozwoli prawidłowo utrzymywać opcje i interfejsy API oraz zmiany w dokumentacji.
- Problem: obecnie dokumentacja w wiki i na stronach ReadTheDocs dotyczy starszych wersji i wymaga gruntownej przebudowy.
- Podstawowe informacje: części scancode-toolkit, które zostały zaktualizowane lub mogą zostać zaktualizowane w wersji, to:
- Opcje wiersza poleceń
- Interfejsy API
- Dokumentacja (do utworzenia): opcje wiersza poleceń i interfejsy API są zmieniane w wersjach i wydaniach, a dokumentacja musi za nimi nadążać, w przeciwnym razie użytkownicy będą mieli problemy. Narzędzie wiersza poleceń [ --help ] jest już aktualizowane w przypadku wszelkich zmian w opcjach i może być używane do replikowania obsługi wersji w dokumentacji.
[ 3. Jak można używać tych opcji w różnych przypadkach ]
- Cel: ta sekcja będzie zawierać podstawowe podsumowanie tego, jak wyniki skanowania scancode-toolkit mogą być używane w różnych celach, oraz opcji scancode-toolkit, które zapewniają taką funkcjonalność.
- Podstawowe informacje: ta sekcja zawiera różne przykłady przypadków użycia i informacje o tym, jakie opcje są zalecane w tych scenariuszach.
- Uwaga: w tej części potrzebna jest znaczna pomoc mentora w zakresie informacji i wskazówek dotyczących różnych przypadków użycia scancode-toolkit.
[ 4. Co te opcje zmieniają w skanowaniu i danych wyjściowych ]
- Cel: ta sekcja będzie zawierać podstawowe podsumowanie tego, jak wyniki skanowania scancode-toolkit mogą być używane w różnych celach, oraz narzędzi Aboutcode, które zapewniają taką funkcjonalność.
- Podstawowe informacje: opcje zmieniają sposób przeprowadzania skanowania. Podstawowy przypadek domyślny zostanie zilustrowany w sekcji [ 1. Wszystkie opcje dostępne w wierszu poleceń ], a ta sekcja będzie porównywać zmiany, które wszystkie opcje wprowadzają w tym domyślnym scenariuszu.
[ 5. Formaty wyjściowe i ich przykłady ]
- Cel: ta sekcja będzie zawierać podstawowe podsumowanie tego, jak wyniki skanowania scancode-toolkit mogą być używane w różnych celach, oraz narzędzi Aboutcode, które zapewniają taką funkcjonalność.
- Podstawowe informacje: scancode-tool ma flagi, które pozwalają określić różne formaty wyjściowe, 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,
- poda inne linki odpowiadające formatowi wyjściowemu i jego użyciu,
- wyjaśni, jak wyniki skanowania są przechowywane w plikach wyjściowych. Zawiera też link do informacji o tym, jak generowane są te różne formaty, co zostanie wyjaśnione w sekcji [ 2. Dyskusje wyjaśniające skanowanie kodu ].
[ 6. Wykorzystanie formatów wyjściowych scancode w firmach ]
- Cele: wyjaśnienie przypadków użycia formatów wyjściowych scancode w firmach. Na liście pomysłów GSoD formaty wyjściowe scancode są wymienione jako pomysł referencyjny. Ta sekcja realizuje ten cel.
- Uwaga: w tej części potrzebna jest znaczna pomoc mentora w zakresie informacji i wskazówek dotyczących różnych przypadków użycia scancode-toolkit w firmach.
[ 7. Jak te dane wyjściowe są używane w innych projektach AboutCode do dalszej analizy ]
- Cel: ta sekcja będzie zawierać podstawowe podsumowanie tego, jak wyniki skanowania scancode-toolkit mogą być używane w różnych celach, oraz narzędzi Aboutcode, które zapewniają taką funkcjonalność.
- Podstawowe informacje:
- Scancode-Workbench: ta część wyjaśnia, jak wizualizować wyniki za pomocą aplikacji na komputer, i zawiera wskazówki dotyczące dokumentacji scancode-workbench, które pomogą w tym zakresie. W razie potrzeby dodam wymaganą dokumentację do scancode-workbench.
- Deltacode: jak Deltacode wykorzystuje wyniki scancode do określania różnic na poziomie plików między 2 bazami kodu.
[ 2. Zmiana struktury dokumentacji AboutCode ]
Ta część zawiera wiele zmian w dokumentacji Aboutcode.
[ 1. System obsługi wersji ]
W sekcji [ 1. Opcje wiersza poleceń w scancode-toolkit -> 2. Wprowadzenie struktury obsługi wersji] wspomniano o problemie z obsługą wersji opcji wiersza poleceń. Jest to konieczne również w przypadku innych części dokumentacji, które zawierają polecenia lub informacje dotyczące konkretnej wersji, co w przeciwnym razie mogłoby powodować zamieszanie.
[ 2. Ustawianie standardów dokumentacji i testów ]
Dokumentacja zawiera już testy spinx-build (który tworzy wszystkie strony i sprawdza, czy nie ma błędów składni Sphinx) oraz test linków (który sprawdza wszystkie linki do innych stron internetowych w dokumentacji) z ciągłą integracją za pomocą Travis-CI. (Dodane przeze mnie w tym żądaniu ściągnięcia #17) Teraz potrzebne są dodatkowe testy pod kątem konkretnego lintingu w reStructured Text i innych standardów. Można to osiągnąć za pomocą restructuredtext-lint, ale wymaga to dalszych badań i zostanie wykonane w ramach mojego projektu GSoD.
[ 3. Dodawanie sekcji „Pierwsze kroki” ]
Będzie to sekcja początkowa dla nowych użytkowników. Będzie zawierać kompilację najważniejszych dokumentów, które pomogą zacząć korzystać z projektów Aboutcode. Każdy projekt Aboutcode będzie miał 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 podzielona na 4 funkcje dokumentu – samouczki, instrukcje, materiały referencyjne i wyjaśnienia. Proponuję odpowiednio ją uporządkować, dodając w razie potrzeby więcej informacji, wyjaśnień i wskazówek. Dotyczy to wszystkich projektów AboutCode i ich dokumentacji. Poniżej znajdziesz 2 przykłady proponowanej zmiany struktury dokumentacji scancode-toolkit, którą chciałbym przeprowadzić w tym projekcie. Podobne zmiany zostaną wprowadzone w pozostałej części dokumentacji.
[ 5. Zmiana struktury strony dotyczącej tworzenia (scancode-toolkit) ]
Można dodać więcej informacji o kodzie i interfejsach API, aby ułatwić pracę deweloperom. Można dodać linki do sekcji [ 2. Dyskusje wyjaśniające skanowanie kodu ] powyżej. Łączy to wyjaśnienie działania skanowania z kodem, którego używa do przeprowadzenia skanowania. Te foldery zawierają różne części scancode-toolkit, a ich indywidualne użycie można opisać za pomocą interfejsów API w połączeniu z dyskusją o tym, jak działa 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 ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : classes for the plugins architecture ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : handles text parsing ]
- [ typecode : handles file type determinations ]
- [ scancode : CLI and API to scancode, the core part ]
Ta podsekcja będzie zawierać szczegółowe informacje i interfejsy API dotyczące tych części scancode-toolkit w odpowiednich podpodsekcjach. Wytyczne dotyczące tworzenia będą dostępne na innej stronie lub w innej sekcji z mniejszymi podsekcjami.
[ 6. Zmiana struktury strony z najczęstszymi pytaniami (scancode-toolkit) ]
Strona z najczęstszymi pytaniami zawiera obecnie pytania, na które można lepiej odpowiedzieć, i powinna być podzielona na osobne instrukcje, samouczki i dokumenty referencyjne.
- Jak działa ScanCode? Ten problem jest opisany w sekcji [ 2. Dyskusje wyjaśniające skanowanie kodu ] i będzie stanowił całkowicie osobną sekcję z dużo większą ilością szczegółów.
- Jak dodać nowe reguły licencji, aby zwiększyć wykrywalność? Ten problem został już omówiony w sekcji Ulepszanie istniejących instrukcji. Dokumentacja zostanie tam przeniesiona.
- Jak dodać nową regułę wykrywania licencji? Można z tego zrobić osobny post „Jak to zrobić” i go rozwinąć.
- Jak zacząć tworzyć? Jest już osobna strona dotycząca tworzenia, a informacje się w dużej mierze pokrywają. Zmiana struktury strony dotyczącej tworzenia została już omówiona powyżej.
- Kroki, aby utworzyć nową wersję. Można to przekształcić w osobny post „Jak utworzyć nową wersję”.
- Znajdź więcej pytań w sekcji Najczęstsze pytania, które odpowiadają na ogólne pytania dotyczące projektu i nie należą do kategorii „Jak to zrobić” ani „Samouczek”.