О проектеCode

На этой странице представлена ​​информация о проекте по написанию технических текстов, принятом для участия в конкурсе Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:
AboutCode
Технический писатель:
айансинха
Название проекта:
Справочник по параметрам командной строки в scancode-toolkit и реорганизация структуры документации AboutCode на aboutcode.readthedocs.io
Длительность проекта:
Стандартная продолжительность (3 месяца)

Описание проекта

[ 1. Параметры командной строки Scancode-Toolkit ]

Scancode-Toolkit предлагает множество параметров командной строки для настройки процесса сканирования, формата вывода и ряда других опций, таких как плагины для постобработки результатов. В настоящее время эти параметры не имеют надлежащей документации и доступны только через флаг «--help» или «-h». Цель этого проекта — создать полную документацию, которая объяснит:

[ 1. Все параметры, доступные через командную строку ]

  • Цель: Полный список всех возможных параметров, доступных через командную строку.
  • Краткий обзор: Сначала рассматриваются параметры сканирования по умолчанию с примером результата. Приводится краткое графическое описание процесса сканирования.
    В дальнейшем это поведение по умолчанию будет служить ориентиром для того, как другие параметры изменяют процесс сканирования и выходные данные.
    Эти вопросы будут подробно рассмотрены и будут содержать следующую информацию, как указано в следующих разделах.

[ 2. Инициализация структуры версионирования ]

  • Цель: Внедрить систему версионирования для надлежащего учета изменений параметров релизов/API и документации.
  • Проблема: В настоящее время документация на вики и страницах ReadTheDocs относится к более старым версиям и нуждается в серьезной реструктуризации.
  • Краткий обзор: В обновленной/возможной для обновления версии scancode-toolkit представлены следующие компоненты:
  • Параметры командной строки
  • 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) и link check (проверяет все ссылки на другие веб-страницы из документации) с использованием непрерывной интеграции через Travis-CI. (Добавлено мной в этом запросе на слияние #17). Теперь необходимы дополнительные проверки для специфического линтинга в reStructured Text и других стандартах. Этого можно достичь с помощью restructuredtext-lint, но это требует дополнительных исследований и будет сделано в рамках моего проекта GSoD.

[ 3. Добавление раздела «Начало работы» ]

Этот раздел послужит отправной точкой для новичков и будет содержать подборку самых основных и важных документов для начала работы с проектами Aboutcode. Каждый проект Aboutcode будет иметь этот раздел, включая Scancode-Toolkit, Scancode-Workbench, Deltacode и другие.

[ 4. Реструктуризация в соответствии с 4 функциями документа ]

Существующая документация не имеет четкой структуры по четырем разделам: «Учебные пособия», «Как это сделать», «Справочник» и «Пояснения». Я предлагаю соответствующим образом структурировать их, добавив необходимую информацию/пояснения/указания. Это касается всех проектов AboutCode и их документации. Ниже приведены два примера предлагаемой мной реструктуризации документации Scancode-Toolkit, которую я хотел бы продолжить в этом проекте. Аналогичные изменения будут внесены и в остальную документацию.

[ 5. Реструктуризация страницы разработки (Scancode-Toolkit) ]

Для повышения удобства разработчиков можно добавить больше информации о коде/API. Можно добавить ссылки на раздел [ 2. Обсуждения, объясняющие сканирование кода ] выше. Это позволит связать объяснение принципа работы сканирования с кодом, используемым для его выполнения. Подобно тому, как эти папки содержат различные части scancode-toolkit, их индивидуальное использование можно подробно описать с помощью API, в сочетании с обсуждением принципа работы scancode.

  • [cleucode: плагины для сканирования лицензий, авторских прав, URL-адресов, электронных писем]
  • [ commoncode : вспомогательные классы и функции]
  • [extractcode: извлекает архивы различных форматов]
  • [ formattedcode : форматирование выходных файлов для различных форматов ]
  • [licensedcode: код обнаружения лицензии]
  • [packagedcode: анализ различных форматов пакетов]
  • [plugincode: классы для архитектуры плагинов]
  • [summarycode: суммирует результаты сканирования обнаруженных лицензий]
  • [ textcode : обрабатывает разбор текста ]
  • [typecode: обрабатывает определение типа файла]
  • [scancode: интерфейс командной строки и API для работы со scancode, основная часть]

В этом подразделе будет представлена ​​подробная информация/API по этим частям scancode-toolkit в соответствующих подподразделах. Руководство по разработке будет размещено на другой странице или в другом разделе, содержащем более мелкие подразделы.

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

В настоящее время на странице часто задаваемых вопросов содержатся вопросы, на которые можно дать более развернутые ответы, и которые следует структурировать в виде отдельных документов: «Как это сделать», «Учебные пособия» и «Справочные материалы».

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