Со-пилотный проект по повышению эффективности

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

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

Организация с открытым исходным кодом:
Второй пилот по производительности
Технический писатель:
арзу14
Название проекта:
Преобразуйте содержимое областей проекта книги в формат readthedocs и reStructuredText, а также улучшите диаграммы.
Длина проекта:
Стандартная продолжительность (3 месяца)

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

АБСТРАКТНЫЙ:

Веб-сайт сообщества играет важную роль в организации с открытым исходным кодом, поскольку он распространяет идею предложений, которые предоставляет сообщество, их ценный вклад, их навыки, их документацию, их учебные пособия и т. д. Итак, мой проект будет направлен на повышение удобства использования. и простота для всех участников открытого исходного кода за счет переноса и обновления содержимого областей проекта книги, то есть содержимого docbook, документации REST API и содержимого уценки pbench, в формат reStructuredText, чтобы его можно было разместить на современном сайте сообщества readthedocs.io. Этот проект также принесет пользу участникам сообщества, поскольку им будет легче изменять и расширять этот контент. Кроме того, в качестве дополнительной цели будут улучшены диаграммы в документации, чтобы придать им более профессиональный вид.

ПРЕДЛОЖЕНИЕ:

  1. ОБЗОР: Документация Performance Co-Pilot в настоящее время существует в нескольких различных форматах. К ним относятся книги PCP в формате docbook, REST API в формате man-страницы и руководства по pbench в формате уценки. Итак, текущая группа сопровождающих организации определила, что им нужно решение, которое было бы максимально не требующим обслуживания и которое позволило бы сообществу разработчиков полностью сосредоточиться на поддержании своего контента рациональным и простым способом. Итак, в соответствии с текущими потребностями организации, в течение этого сезона документации Google я буду реализовывать следующие цели:

    1. Преобразование содержимого документа в формат reStructuredText и размещение его на сайте readthedocs.
    2. Преобразование документации REST API из man-страницы в удобный для разработчиков формат, т. е. формат reStructuredText, и размещение ее на сайте readthedocs.
    3. Преобразование содержимого pbench MarkDown в формат reStructuredText и размещение его на сайте readthedocs.
    4. Целью расширения будет улучшение диаграмм, представленных в документации.

  2. РЕАЛИЗАЦИЯ: В настоящее время документация Performance Co-Pilot не представлена ​​в определенном формате. Всякий раз, когда содержание документации необходимо изменить, оно должно быть изменено ограниченным кругом пользователей. Активным членам сообщества не так-то просто изменять и расширять содержание документации.

Я позволю организации преодолеть эти ограничения во время этого GSoD с помощью формата reStructuredText, Read the Docs (RTD) и Sphinx.

Read the Docs (RTD) упрощает документацию по программному обеспечению, автоматизируя создание, управление версиями и размещение нашей документации для нас. Это хостинговая платформа для документации, созданной Sphinx. Он использует возможности Sphinx и добавляет контроль версий, полнотекстовый поиск и другие полезные функции. Он извлекает код и файлы документации из Git, Mercurial или Subversion, а затем собирает и размещает нашу документацию. В нашем проекте мы будем использовать GitHub, поскольку это наиболее часто используемая система доступа к коду.

Для начала мы создадим учетную запись Read the Docs и свяжем ее с учетной записью GitHub. Затем мы выберем репозиторий GitHub, для которого хотим создать документацию, и в этот момент произойдет волшебство.

Прочитав документацию, вы: - Клонируете наш репозиторий. - Создавайте версии нашей документации в формате HTML, PDF и ePub из нашей основной ветки. - Индексируйте нашу документацию, чтобы обеспечить полнотекстовый поиск. — Создавайте объекты версии из каждого тега и ветки в нашем репозитории, что позволяет нам также размещать их по желанию. — Активируйте вебхук в нашем репозитории, чтобы при отправке кода в любую ветку наша документация перестраивалась.

Sphinx — это авторитетный генератор документации, который имеет множество замечательных функций для написания технической документации, в том числе: — Создание веб-страниц, PDF-файлов для печати, документов для электронных книг (ePub) и многого другого из одних и тех же источников. — Мы можем использовать reStructuredText для написания документации. - Обширная система перекрестных ссылок на код и документацию. - Синтаксис выделенных примеров кода. - Активная экосистема собственных и сторонних расширений.

Я начну с преобразования двух книг PCP, представленных в формате docbook, в первый формат, после чего преобразую документацию REST API из формата man-страницы в первый формат, затем преобразую содержимое уценки pbench в первый формат и, наконец, размещаю все из них на сайте readthedocs. Целью расширения будет улучшение диаграмм в документации.

2.1. Преобразование в формат reStructuredText. Первым шагом будет преобразование содержимого документации в формат reStructuredText. Каждая глава будет иметь отдельный первый файл, который будет содержать только содержимое этой главы. Например, Руководство пользователя и администратора Performance Co-Pilot включает восемь глав. Это означает, что будет восемь разных первых файлов, соответствующих этим восьми главам. Имя первого файла будет таким же, как название главы, чтобы избежать путаницы в будущем. Список рисунков, таблиц и примеров будет находиться в трех разных файлах. Первый контент будет снабжен гиперссылками точно так же, как он присутствует в настоящее время. То же самое будет использоваться для документации REST API и содержимого pbench. Все необходимые вещи, такие как жирный шрифт, курсив, подчеркивание, маркеры, таблицы, размер шрифта, стиль кода, размер изображения, выравнивание и т. д., будут учтены при преобразовании содержимого в первый формат.

2.2. Интеграция первой со Sphinx:

ReadtheDocs использует Sphinx и reStructuredText (первый) по умолчанию. Поскольку Sphinx предустановлен в моей системе, я начну с создания каталога внутри проекта (названного Performance Co-Pilot Documentation) для хранения документации: $ cd /path/to/project $ mkdir docs

После этого запускаем sphinx-quickstart: $ cd docs $ sphinx-quickstart

В этом кратком руководстве описан процесс создания необходимой конфигурации; в большинстве случаев мы можем просто принять значения по умолчанию (но при необходимости мы можем внести существенные изменения в файл конфигурации). Когда это будет сделано, у нас будут index.rst, conf.py и некоторые другие файлы. В index.rst я добавлю все необходимые сведения о Performance Co-Pilot и создам заголовки как для книг, документации по REST API, так и для руководств по pbench. Когда пользователь щелкнет любой из заголовков, он откроет все материалы документации под этим заголовком.

ПРИМЕЧАНИЕ. Дизайн индексной страницы будет согласован с наставниками и членами сообщества и будет изменен в соответствии с потребностями и требованиями.

Файл index.rst будет встроен в index.html в выходном каталоге нашей документации (обычно _build/html/index.html). Как только у нас появится документация Sphinx в общедоступном репозитории, мы сможем начать использовать Read the Docs, импортировав наши документы.

Когда мы добавим какой-либо файл .rst в нашу документацию, то в соответствии с этим файлом будут созданы три других файла: один в папке doctrees с расширением .doctree, второй в папке Html с расширением .html и третий в html. Папка /_sources с расширением .rst.txt.

  1. ХОСТИНГ ДОКУМЕНТАЦИИ. Размещение документации в Интернете состоит из двух этапов: 1. Импорт документации. На первом этапе я подключаю учетную запись Read The Docs к GitHub и импортирую наш проект документации для сборки. 2. Создание документации. Через несколько секунд после завершения процесса импорта код будет автоматически получен из нашего общедоступного репозитория, и документация будет создана.

  2. ВЕБХУКЫ. Основной метод, который Read the Docs использует для обнаружения изменений в документации и версиях, — это использование веб-перехватчиков. Веб-перехватчики настраиваются с помощью нашего поставщика репозитория, такого как GitHub, и при каждой фиксации, слиянии или другом изменении в нашем репозитории появляется уведомление Read the Docs. Когда мы получаем уведомление веб-перехватчика, мы определяем, связано ли изменение с активной версией нашего проекта, и если да, то для этой версии запускается сборка.

Таким образом, любой (администраторы, наставники, участники сообщества) может изменять, расширять или поддерживать документацию сообщества, и не требуется никакого определенного ограниченного круга пользователей, чтобы заботиться о том, что следует добавить в документацию или что следует удалить из нее. документация.

  1. ТЕМЫ. Темы, макеты, дизайн и другие функции HTML, такие как поиск, будут соответствовать потребностям и рекомендациям сообщества. В период сплочения сообщества я буду обсуждать все это с членами сообщества.
  1. РАСШИРЕНИЕ ЦЕЛИ: В качестве дополнительной цели я улучшу диаграммы, представленные в документации. В настоящее время диаграммы представляют собой в основном простые черно-белые рисунки. Я добавлю больше цвета, теней, масштабирования, последовательности и, в целом, более аккуратного/профессионального вида изображениям.

Для этой цели я буду использовать draw.io (или любой другой инструмент с согласия наставника).

В качестве доказательства концепции я улучшил одну из диаграмм, представленных в документации, с помощью draw.io. Найдите его здесь: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing.

ДОКАЗАТЕЛЬСТВО КОНЦЕПЦИИ

Я конвертировал небольшую часть книги PCP (формат docbook) в первый формат и разместил ее на сайте readthedocs. Пожалуйста, найдите это здесь.

Веб-сайт — https://pcp-books.readthedocs.io/en/latest/ Код — https://github.com/arzoo14/PCP_Books_Demo

Я также настроил веб-хуки в репозитории кода, с помощью которых изменения, внесенные в репозиторий кода, будут отражены на веб-сайте.

СРОКИ И РЕЗУЛЬТАТЫ

ПЕРИОД ОБЪЕДИНЕНИЯ СООБЩЕСТВ [17 августа - 13 сентября 2020 г.]

Я потрачу это время на знакомство с сообществом, просмотр документации и обсуждение многих вещей с наставниками, чтобы убедиться, что на ранних этапах процесса не будет принято плохих решений. В течение этого периода я буду обсуждать темы, макеты, дизайн, другие функции, такие как поиск, панель навигации и т. д., с наставниками и членами сообщества. Решение о названии проекта и о том, будет ли один веб-сайт для размещения всех трех тем или три разных веб-сайта, соответствующих трем темам, будут обсуждаться в период объединения сообщества.

ПЕРИОД РАЗРАБОТКИ ДОКУМЕНТА [14 сентября – 30 ноября 2020 г.]

***С 14 по 20 сентября 2020 г. [НЕДЕЛЯ 1] Преобразование содержимого docbook в первый формат для первых четырех глав Руководства пользователей и администраторов.

***С 21 сентября 2020 г. по 27 сентября 2020 г. [НЕДЕЛЯ 2] Преобразование содержимого документа в первый формат для следующих четырех глав Руководства пользователей и администраторов.

***С 28 сентября 2020 г. по 4 октября 2020 г. [НЕДЕЛЯ 3] Преобразование содержимого docbook в первый формат для всех четырех глав книги «Руководство программиста».

***С 5 октября 2020 г. по 11 октября 2020 г. [НЕДЕЛЯ 4] — размещение обеих книг PCP на сайте readthedocs. — Преобразование документации REST API со страницы руководства в первый формат. В этот период будет закрыта главная целевая страница. - Ведение блога (моего проекта GSoD) за последние три недели и текущую неделю.

***С 12 октября 2020 г. по 18 октября 2020 г. [НЕДЕЛЯ 5] Преобразование индекса масштабируемых временных рядов в первый формат. Индекс масштабируемых временных рядов охватывает следующее: GET /series/query , GET /series/values ​​, GET /series/descs , GET /series/labels , GET /series/metrics , GET /series/sources , GET /series/instances , ПОЛУЧИТЬ /серия/загрузка

***С 19 октября 2020 г. по 25 октября 2020 г. [НЕДЕЛЯ 6] Преобразование индекса PMAPI Host Services в первый формат. Индекс PMAPI Host Services охватывает следующее: GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch, GET /pmapi/children GET /pmapi/indom, GET /pmapi/profile, GET /pmapi/store, GET /pmapi/вывести GET /pmapi/metrics

***С 26 октября 2020 г. по 1 ноября 2020 г. [НЕДЕЛЯ 7] — Если что-то останется в последние недели, это будет рассмотрено в первую очередь. — Размещение документации по REST API на сайте readthedocs. - Ведение блога (моего проекта GSoD) за последние две недели и текущую неделю.

***С 2 по 8 ноября 2020 г. [НЕДЕЛЯ 8] Преобразование содержимого уценки в первый формат для руководств pbench.

***С 9 ноября 2020 г. по 15 ноября 2020 г. [НЕДЕЛЯ 9] — продолжено преобразование содержимого уценки в первый формат для руководств pbench. - Размещение руководств по pbench на сайте readthedocs. - Ведение блога (моего проекта GSoD) за прошедшую и текущую неделю.

***С 16 ноября 2020 г. по 22 ноября 2020 г. [НЕДЕЛЯ 10] - Реализация функционала поиска на индексной странице для поиска любого контента по его названию на сайте(ах). - Начало амбициозных целей.

***С 23 ноября 2020 г. по 30 ноября 2020 г. [НЕДЕЛЯ 11] - Улучшение всех диаграмм, присутствующих в документации. - Итоговый блог (моего проекта GSoD) за прошедшую и текущую неделю. - Проверка соответствия кодовой базы стандартам кодирования или нет. Если нет, то меняем их на стандарты.

ПЕРИОД ЗАВЕРШЕНИЯ ПРОЕКТА [30 ноября – 5 декабря 2020 г.]

  • Карандаш простоя. Работаем над финальным представлением и проверяем, что все в порядке.
  • Представление отчетов по проекту, также известных как окончательные рабочие продукты.
  • Предоставление оценок успешности проектов и опыта работы с менторами.