На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- О коде
- Технический писатель:
- Аянсинха
- Название проекта:
- Ссылка на параметры командной строки в scancode-toolkit и реорганизацию структуры документации AboutCode на сайте aboutcode.readthedocs.io.
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
[ 1. Параметры командной строки Scancode-Toolkit ]
Scancode-Toolkit имеет множество параметров командной строки для настройки способа выполнения сканирования, формата вывода и нескольких других параметров, таких как плагины после сканирования. Эти параметры в настоящее время не имеют надлежащей документации, объясняющей их, и доступны только через флаг «--help» или «-h». Целью этого проекта является создание полной документации, объясняющей:
[1. Все параметры, доступные через командную строку]
- Цель: исчерпывающий список всех возможных опций через командную строку.
- Базовый обзор. Сначала обсуждаются параметры сканирования по умолчанию и приводится пример выходных данных. Краткое изображение/описание того, как выполняется сканирование.
В дальнейшем это поведение по умолчанию действует как ссылка на то, как другие параметры изменяют сканирование и вывод.
Они подлежат подробному обсуждению и будут содержать следующую информацию, упомянутую в следующих разделах.
[2. Инициирование структуры версий]
- Цель: Инициировать систему управления версиями для надлежащего управления опциями перекрестных выпусков/API и изменениями документации.
- Проблема: в настоящее время документация в вики и на страницах ReadTheDocs предназначена для более старых версий и требует серьезной реструктуризации.
- Базовый обзор: Части набора инструментов сканирования, которые были обновлены/могут быть обновлены в версии:
- Параметры командной строки
- API
- Документация (необходимо начать). Параметры командной строки и API изменяются в версиях и выпусках, и документация также должна следовать за ней, иначе это создаст огромную путаницу для пользователей. Утилита командной строки [ --help ] уже обновлена для любых изменений в параметрах и может использоваться для репликации версий в документации.
[3. Как эти опции можно использовать в разных случаях]
- Цель: в этом разделе будет представлено общее описание того, как результаты сканирования scancode-toolkit могут быть использованы в различных целях, а также параметры Scancode-Toolkit, обеспечивающие такую функциональность.
- Базовый обзор. В этом разделе приведены примеры сценариев различных вариантов использования и параметры, рекомендуемые в этих сценариях.
- Примечание. В этой части требуется значительная помощь наставника в виде информации и указаний на различные варианты использования Scancode-Toolkit.
[4. Что меняют эти параметры при сканировании и выводе]
- Цель: в этом разделе будет представлено общее описание того, как результаты сканирования scancode-toolkit можно использовать в различных целях, а также инструментов Aboutcode, которые обеспечивают такую функциональность.
- Базовый обзор: параметры изменяют способ выполнения сканирования. Базовый случай по умолчанию будет проиллюстрирован в начальном разделе [1. Все параметры, доступные через командную строку], и в этом разделе будут сравниваться изменения, которые все параметры вносят в этот сценарий по умолчанию.
[5. Форматы вывода и их примеры]
- Цель: в этом разделе будет представлено общее описание того, как результаты сканирования scancode-toolkit можно использовать в различных целях, а также инструментов Aboutcode, которые обеспечивают такую функциональность.
- Базовый обзор: Scancode-Tool имеет флаги для указания различных выходных форматов, в которых будут генерироваться результаты сканирования. Это -
Эта часть будет - подробно объяснить форматы вывода
- приведите примеры выходных форматов
- дайте другие ссылки, соответствующие выходному формату и его использованию
- как результаты сканирования сохраняются в выходных файлах. Это также связано с тем, как генерируются эти различные форматы, что будет объяснено в [2. Обсуждения, объясняющие сканирование кода].
[6. Использование форматов вывода сканкода в бизнесе]
- Цели: объяснить варианты бизнес-использования форматов вывода сканкода. В списке идей GSoD форматы вывода сканкода упоминаются как справочная идея. В этом разделе реализовано то же самое.
- Примечание. В этой части требуется значительная помощь наставника с точки зрения информации и указаний на различные варианты использования Scancode-Toolkit в бизнесе.
[7. Как эти результаты используются другими проектами AboutCode для дополнительного анализа]
- Цель: в этом разделе будет представлено общее описание того, как результаты сканирования scancode-toolkit можно использовать в различных целях, а также инструментов Aboutcode, которые обеспечивают такую функциональность.
- Базовый обзор:
- Scancode-Workbench В этой части объясняется визуализация результатов с помощью настольного приложения и ссылки на документацию scancode-workbench для получения дополнительной поддержки. При необходимости добавит необходимую документацию в scancode-workbench.
- Deltacode Как результаты сканирования Deltacode используются для определения различий на уровне файлов между двумя базами кода.
[2. Реорганизовать структуру документации AboutCode]
Эта часть включает в себя множество изменений в документации Aboutcode.
[ 1. Система управления версиями ]
В [ 1. Параметры командной строки Scancode-Toolkit -> 2. Инициировать структуру управления версиями] упоминается проблема управления версиями параметров командной строки. То же самое необходимо и для других частей документации, которые также содержат команды/информацию для конкретной версии, которые в противном случае могли бы создать путаницу.
[2. Установление стандартов документации и тестов]
В документации уже есть тесты для spinx-build (собирает все страницы и проверяет наличие синтаксических ошибок Sphinx) и проверки ссылок (проверяет все ссылки на другие веб-страницы из документации) с непрерывной интеграцией через Travis-CI. (Добавлено мной в этот запрос на извлечение № 17). Теперь требуется больше проверок для конкретного анализа в реструктурированном тексте и других стандартах. Этого можно достичь с помощью реструктурированного text-lint, но это требует дополнительных исследований и будет выполнено в рамках моего проекта GSoD.
[3. Добавление раздела «Начало работы»]
Он будет служить стартовым разделом для новичков и будет содержать подборку самых основных и важных документов для начала работы с проектами Aboutcode. Каждый проект Aboutcode будет иметь этот раздел, включая Scancode-Toolkit, Scancode-Workbench, Deltacode и другие.
[ 4. Реструктуризация по 4 функциям документа ]
Существующая документация не структурирована явно по 4 функциям документа: учебные пособия, инструкции, ссылки и пояснения. Я предлагаю структурировать их соответствующим образом, добавляя при необходимости дополнительную информацию/объяснения/указатели. Это справедливо для всех проектов AboutCode и их документации. Ниже приведены два примера реструктуризации документации Scancode-Toolkit, которую я предлагаю и хотел бы продолжить в этом проекте. Аналогичные изменения будут проведены и в остальной документации.
[5. Реструктуризация страницы разработки (Scancode-Toolkit)]
Можно добавить дополнительную информацию о коде/API, чтобы сделать его более удобным для разработчиков. Могут быть ссылки на раздел [2. Обсуждения, объясняющие сканирование кода] выше. Это связывает объяснение того, как работает сканирование, с кодом, который он использует для выполнения сканирования. Поскольку эти папки содержат различные части набора инструментов scancode, их индивидуальное использование может быть уточнено с помощью API в сочетании с обсуждением того, как работает scancode.
- [код подсказки: плагины для сканирования лицензий, авторских прав, URL-адресов, электронных писем]
- [общий код: вспомогательные классы и функции]
- [extractcode: извлекает архивы разных форматов]
- [formatedcode: форматирование вывода для различных форматов выходных файлов]
- [licensedcode: код обнаружения лицензии]
- [packedcode: анализ различных форматов пакетов]
- [код плагина: классы архитектуры плагинов]
- [summarycode: суммирует сканирование обнаруженных лицензий]
- [текстовый код: обрабатывает анализ текста]
- [код типа: обрабатывает определение типа файла]
- [сканкод: CLI и API для сканирования кода, основная часть]
Этот подраздел будет содержать подробную информацию/API по этим частям набора инструментов сканирования в соответствующих подразделах. Рекомендации по разработке будут находиться на другой странице или в другом разделе с меньшими подразделами.
[ 6. Реструктуризация страницы часто задаваемых вопросов (Scancode-Toolkit) ]
На странице часто задаваемых вопросов в настоящее время есть вопросы, на которые можно лучше ответить, и их следует структурировать как отдельные инструкции, учебные пособия и справочные документы.
- Как работает СканКод? Эта проблема упоминается в [2. Обсуждения, объясняющие сканирование кода] и будет посвящена совершенно отдельному разделу с гораздо более подробной информацией.
- Как добавить новые правила лицензии для улучшенного обнаружения? Этот вопрос уже обсуждался ранее в разделе «Улучшение существующих инструкций», документация будет перенесена туда.
- Как добавить новое правило определения лицензии? Это можно было бы превратить в отдельный пост «Как сделать» и детализировать.
- Как начать разработку? Уже есть отдельная страница разработки, и информация во многом пересекается. О реструктуризации страницы разработки уже говорилось выше.
- Действия по вырезанию нового выпуска. Это можно преобразовать в отдельный раздел «Как вырезать новый выпуск».
- Найдите дополнительные часто задаваемые вопросы, которые отвечают на общие вопросы о проекте и не попадают в категории «Как сделать» или «Учебное пособие».