Документация#

Совет

Документация на сайте выполнена в стандарте ReStructuredText (RST). Пожалуйста, пример файла RST, если Вам этот стандарт не знаком.

Эта страница поможет Вам подготовить хорошую документацию для проекта UBports. Тесты будут размещены на сайте.

Инструкция по подготовке документации#

Эти правила задают порядок оформления документации, чтобы избежать проблем со стилем, форматом текста или ссылками. Если Вы не будете следовать этим рекомендациям, мы будем вынуждены отказать в публикации Вашего документа.

Заголовок#

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

Заголовки должны быть написаны в верхнем регистре, а не просто заглавными буквами. Например:

Incorrect casing:
    Writing A Good Bug Report
Correct casing:
    Writing a good bug report
Correct casing when proper nouns are involved:
    Installing Ubuntu Touch on your phone

Не существует какого-то единого определения списка заголовков, которому следуют все пользователи, но на предложения разделять их легко. Это помогает сформировать стандартное оглавление.

Заголовки страниц выделены знаком равенства. Например, в разделе Подготовка баг-репортов заголовок выглядит так:

Bug reporting
=============

Помните что:

Заголовок нужно писать заглавными буквами
Заголовок выделяется знаками равенства
Линия подчеркивания не переходит за границы заголовка

Неправильные примеры заголовков:

Некорректный регистр букв
Bug Reporting =============
Линия подчёркивания слишком короткая
Bug reporting =====
Линия подчёркивания слишком длинная
Bug reporting ================

Заголовки#

Есть несколько уровней заголовков, которые вы можете разместить на своей странице. Эти уровни показаны здесь по порядку:

Page title
==========

Level one
---------

Level two
^^^^^^^^^

Level three
"""""""""""

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

Содержание#

Пользователи не могут перейти на новую страницу, если не могут ее найти. Это справедливо и для системы Sphinx. Поэтому сначала нужно добавить страницы в оглавление Sphinx.

Это можно сделать, добавив страницу в файл index.rst, который находится в этой же папке. Например, если вы создадите файл с именем «newpage.rst», добавьте строку строку в индексный файл и обозначьте ее символом (>):

.. toctree::
    :maxdepth: 1
    :name: example-toc

    oldpage
    anotheroldpage
>   newpage

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

Перенос страниц#

Иногда нужно переместить страницу из одного раздела документации в другой. Как правило, это делается для улучшения структуры документов. Например, если какая-то глава должна находиться в другом разделе.

Однако ссылки на документацию есть во многих источниках, и все их не проконтролировать. Блоги, веб-сайты и всякие справочные ресурсы могут направлять сюда пользователей по устаревшим ссылкам. Для пользователя это не несёт ничего хорошего - большинство таких переходов заканчиваются «ошибкой 404», так как документация уже сильно переработана к этому моменту.

Чтобы избежать подобных ошибок, есть утилита Rediraffe. Rediraffe создает страницы-редиректы, которые могут перенаправить пользователя со старой недействительной ссылки на новую страницу. Создайте ссылку-редирект при изменении имени страницы или перемещении страницы в структуре каталогов документации. Такие ссылки создаются в файле redirects.txt.

Для проверки страниц используется инструмент checkdiff, входящий в утилиту Rediraffe. Он позволяет не удалять страницы без редиректов из документации. Этот инструмент запускается скриптом build.sh в репозитории при процедуре автоматической сборки после отправки запроса Pull Request.

Ниже разобраны несколько примеров ситуаций, когда нужно создавать редиректы.

Нужно переместить файл из папки systemdev/calendars.rst в папку appdev/calendars.rst. В файле redirects.txt нужно указать следующее:

"systemdev/calendars.txt" "appdev/calendars.txt"

Нужно переместить главу``appdev/clickable.rst`` в раздел appdev/clickable/, так как она стала занимать больше, чем несколько страниц, и появилась новая информация об этом приложении. В разделе есть страничка с введением appdev/clickable/introduction.rst. В этом случае можно перенаправить старую страницу на новую часть с введением. Это можно сделать, добавив в redirects.txt следующее:

"appdev/clickable.rst" "appdev/clickable/introduction.rst"

Предупреждения и ошибки#

Правки не должны вносить никаких ошибок в раздел с документацией. Если появятся какие-либо предупреждения или ошибки, сборка завершится неудачно, и запрос на компиляцию будет помечен красным крестиком. Пожалуйста, убедитесь, что ваш RST-файл является правильным, прежде чем запускать процесс сборки. Это произойдет автоматически (через sphinx-build crashing), если Вы будете выполнять инструкции по созданию документации, приведённые ниже.

Длина строки#

Ограничений на длину строки нет (для этого репозитория). Пожалуйста, не создавайте строк разной длины. Настройте в текстовом редакторе автоматический перенос.

Редактирование и внесение правок#

Следующие действия помогут внести исправления в документ после того, как он был опубликован.

Примечание

Вам понадобится учетная запись на GitHub, чтобы закончить перевод. Если Вы не зарегистрированы на этом ресурсе, сделайте это по ссылке.

Клонирование (форк) репозитория#

Можно существенно переработать документацию, но для этого лучше сделать копию (форк) проекта ubports/docs.ubports.com на сайте GitHub. Если у Вас есть вопросы по этому процессу, прочитайте подробное руководство на сайте GitHub.

Сборка комплекта документации#

Если Вы хотите скомпилировать пакет с комплектом документации до отправки нам pull request, эти инструкции помогут работать с локальной копией или форком репозитория.

Комплект документации можно скомпилировать, запустив скрипт ./build.sh в корневой директории этого репозитория. Скрипт также создаст виртуальное рабочее окружение в директории ~/ubportsdocsenv, если его еще нет.

Если скрипт успешно отработал, появятся директории _build/html, где будет находится файл с документацией``index.html``.

Если у Вас возникают проблемы при компиляции пакета документации, сначала попробуйте удалить рабочую среду для формирования сборки. Запустите команду rm -r ~/ubportsdocsenv и попробуйте снова запустить процесс сборки. В зависимости от рабочего окружения может потребоваться команда sudo перед rm.

Финальные проверки#

После того, как на github создан запрос PR, система непрерывной интеграции CI сформирует тестовую сборку. Пожалуйста, проверьте несколько раз, успешно ли выполняется сборка есть ли нужный результат:

Откройте вкладку «Conversation» в запросе PR на github. Здесь можно посмотреть состояние проверок (возможно, придется нажать «Показать все проверки»)
На вкладке может быть желтая точка, то есть статус «ожидание». Нужно подождать несколько секунд.
Или на вкладке может быть пиктограмма с красным крестиком, т.е. проверка завершилась неудачно. В этом случае проверьте, какие указаны причины
Если отображается зеленая галочка, это значит, что запрос PR может быть успешно обработан
Теперь нажмите вкладку «Подробнее»,
затем «Артефакты» вверху справа,
затем «_build/html/..index.html»,
и, наконец, «Перейти на стартовую страницу».

Теперь можно просмотреть сформированный комплект документации UBports с внесёнными правками. Несколько раз проверьте, как выглядят внесённые правки.

Как еще можно помочь#

Перевод на другие языки#

Можно перевести инструкции и разделы документации в специальном проекте по переводам на ресурсе UBports Weblate.

Подготовка документации в форматах, отличных от RST#

Если Вы хотите написать инструкции по продуктам UBports, но по каким-то причинам не можете оформлять текст в формате ReStructuredText, пожалуйста, разместите текст без форматирования в форуме сообщества UBports Forum в соответствующем разделе (скорее всего, в разделе «General»). Кто-нибудь из пользователей отредактирует черновик и переведёт его в формат ReStructuredText.

Если нет возможности работать с Git#

Если Вы подготовили документ в формате ReStructuredText, но по каким-то причинам не можете использовать Git или GitHub, пожалуйста, опубликуйте его в в соответствующем разделе форума UBports Forum (например, в разделе General). Кто-нибудь из пользователей посмотрит черновик и перенесёт его в раздел документации.

Планы по дополнению и развитию этого раздела#

В этой секции содержится список планов на будущее и недоработок, которые нужно устранить. Если Вы знаете, как это сделать, пожалуйста создайте соответствующий pull request на трекере.

Чтобы создать такой список, добавьте на свою страничку этот шаблон:

.. todo::

   My todo text

План

There is also another way to create somewhat more featureful webapps, sometimes referred to as webapp+ or alternative container. This needst to be properly documented. It’s a simple qml app that can be easily configured. Creation is almost as simple as „classic“ webapp, but result is more powerfull with the a nice navigation feature. A rather advanced example of this is the YouTube app from Mateo Salta which has quite some modifications on top of the template.

(исходный элемент находится в /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-ru/checkouts/latest/appdev/webapp/index.rst, строка 19.)

План

Подготовить инструкции для смартфона Nexus 4 (mako)

(исходный элемент находится в /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-ru/checkouts/latest/systemdev/kernel-hal.rst, строка 57.)