О проектеCode

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в 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: форматирование вывода для различных форматов выходных файлов]
  • [licencedcode: код обнаружения лицензии]
  • [packedcode: анализ различных форматов пакетов]
  • [код плагина: классы архитектуры плагинов]
  • [summarycode: суммирует сканирование обнаруженных лицензий]
  • [текстовый код: обрабатывает анализ текста]
  • [код типа: обрабатывает определение типа файла]
  • [сканкод: CLI и API для сканирования кода, основная часть]

Этот подраздел будет содержать подробную информацию/API по этим частям набора инструментов сканирования в соответствующих подразделах. Рекомендации по разработке будут находиться на другой странице или в другом разделе с меньшими подразделами.

[ 6. Реструктуризация страницы часто задаваемых вопросов (Scancode-Toolkit) ]

На странице часто задаваемых вопросов в настоящее время есть вопросы, на которые можно лучше ответить, и их следует структурировать как отдельные инструкции, учебные пособия и справочные документы.

  • Как работает СканКод? Эта проблема упоминается в [2. Обсуждения, объясняющие сканирование кода] и будет посвящена совершенно отдельному разделу с гораздо более подробной информацией.
  • Как добавить новые правила лицензии для улучшенного обнаружения? Этот вопрос уже обсуждался ранее в разделе «Улучшение существующих инструкций», документация будет перенесена туда.
  • Как добавить новое правило определения лицензии? Это можно было бы превратить в отдельный пост «Как сделать» и детализировать.
  • Как начать разработку? Уже есть отдельная страница разработки, и информация во многом пересекается. О реструктуризации страницы разработки уже говорилось выше.
  • Действия по вырезанию нового выпуска. Это можно преобразовать в отдельный раздел «Как вырезать новый выпуск».
  • Найдите дополнительные часто задаваемые вопросы, которые отвечают на общие вопросы о проекте и не попадают в категории «Как сделать» или «Учебное пособие».