Documentation¶
Совет
Документация на сайте выполнена в стандарте ReStructuredText (RST). Пожалуйста, пример файла RST, если Вам этот стандарт не знаком.
Эта страница поможет Вам подготовить хорошую документацию для проекта UBports. Тесты будут размещены на сайте.
Инструкция по подготовке документации¶
These rules govern how you should write documentation to avoid problems with style, format or linking.
Заголовок¶
На всех страницах должен быть заголовок, который будет показан в оглавлении (левая боковая панель) и в верхней части страницы.
Заголовки должны быть написаны в верхнем регистре, а не просто заглавными буквами. Например:
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 ================
Заголовки¶
There are several levels of headings that you may place on a page. These levels are shown here in order:
Page title
==========
Level one
---------
Level two
^^^^^^^^^
Level three
"""""""""""
Please refrain from using more than four levels. If you think you need more levels, it is a good sign that the document should be split up into multiple pages. Furthermore the web version of the documentation only shows four levels in it’s table of contents.
Содержание¶
If you add a new page you also have to add it to the table of contents. You can do this by adding the page to the index.rst file in the same directory where you created it. For example, if you create a file called «newpage.rst», you would add the line marked with a chevron (>) in the nearest index:
.. toctree::
:maxdepth: 1
:name: example-toc
oldpage
anotheroldpage
> newpage
The order matters. If you would like your page to appear in a certain position in the table of contents, place it there. In the previous example, newpage would be added to the end of this table of contents.
Перенос страниц¶
Иногда нужно переместить страницу из одного раздела документации в другой. Как правило, это делается для улучшения структуры документов. Например, если какая-то глава должна находиться в другом разделе.
However, people link to our documentation from many sources that we do not control. Blogs, websites, and other documentation sites can direct people here using links that they may never update. It is a terrible experience to follow a link from a different site and land on a 404 page, being forced to search manually in our documentation.
We use a tool called Rediraffe to avoid such a bad experience. Rediraffe creates redirect pages, which can send a user from an old, invalid link to a new, useful link. Please create a redirect link when changing a page’s name or moving a page within the documentation’s directory structure. Redirect links are created by placing the filename of the old document and the filename of the new document, relative to the documentation’s root, in the redirects.txt file.
We use Rediraffe’s checkdiff builder to ensure that pages are not deleted from the documentation without a redirect in place. This builder is run as part of the build.sh script in the repository and as part of our automated build once you submit a Merge Request (MR).
Ниже разобраны несколько примеров ситуаций, когда нужно создавать редиректы.
Нужно переместить файл из папки 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"
Предупреждения и ошибки¶
Your edits must not introduce any warnings into the documentation build. If any warnings occur, the build will fail and the merge request will be marked with a red „X“. Please ensure that your RST is valid and correct before you create a merge request. This is done automatically (via sphinx-build crashing with your error) if you follow our build instructions below.
Длина строки¶
Ограничений на длину строки нет (для этого репозитория). Пожалуйста, не создавайте строк разной длины. Настройте в текстовом редакторе автоматический перенос.
Редактирование и внесение правок¶
The following steps explain how you can make a contribution to this documentation.
Примечание
You will need a GitLab account to complete these steps. If you do not have an account, go to gitlab.com to create one.
Клонирование (форк) репозитория¶
You can make more advanced edits to the documentation by forking ubports/docs.ubports.com on GitLab.
Сборка комплекта документации¶
To build this documentation, follow these instructions on your local copy of your fork of the repository.
Комплект документации можно скомпилировать, запустив скрипт ./build.sh в корневой директории этого репозитория. Скрипт также создаст виртуальное рабочее окружение в директории ~/ubportsdocsenv, если его еще нет.
Если скрипт успешно отработал, появятся директории _build/html, где будет находится файл с документацией``index.html``.
If you have trouble building the docs, the first thing to try is deleting the build environment. Run rm -r ~/ubportsdocsenv and try the build again.
Финальные проверки¶
After you have created your Merge Request on GitLab, the Continuous Integration (CI) system will make a test build of your contribution (a «pipeline»). Please double check whether this builds successfully and whether the result looks as you intended it to:
at the top of the «Overview» tab of your MR on gitlab you will see the status of the pipeline
if it says «Checking pipeline status» or «Pipeline running» then please wait another minute.
if it says «Pipeline failed» with a red X and, then something went wrong, please click on the link to find the details
if it says «Pipeline passed» with green check mark, it means the MR could be built successfully and you can proceed to look at the results
now please click on link of that pipeline
click on «build» job
this brings you to the end of the build log, where you’ll see a message: «Build succeeded, browse the artifact here»
click the link next to it to see the full version of the UBports documentation site with your changes
double check whether your changes look ok
Как еще можно помочь¶
Translations¶
Можно перевести инструкции и разделы документации в специальном проекте по переводам на ресурсе UBports Weblate.
Подготовка документации в форматах, отличных от RST¶
Если Вы хотите написать инструкции по продуктам UBports, но по каким-то причинам не можете оформлять текст в формате ReStructuredText, пожалуйста, разместите текст без форматирования в форуме сообщества UBports Forum в соответствующем разделе (скорее всего, в разделе «General»). Кто-нибудь из пользователей отредактирует черновик и переведёт его в формат ReStructuredText.
Если нет возможности работать с Git¶
If you’ve written a complete document in ReStructuredText but aren’t comfortable using Git or GitLab, please post it on the UBports Forum in the relevant section (likely General). Someone will be able to help you revise your draft and submit it to this documentation.
Планы по дополнению и развитию этого раздела¶
This section lists the TODOs that have been included in this documentation. If you know how to fix one, please send us a merge request to make it better!
Чтобы создать такой список, добавьте на свою страничку этот шаблон:
.. 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-gitlab-ru/checkouts/latest/appdev/webapp/index.rst, строка 19.)
План
Подготовить инструкции для смартфона Nexus 4 (mako)
(исходный элемент находится в /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-ru/checkouts/latest/systemdev/kernel-hal.rst, строка 57.)
ReadTheDocs hosting¶
The actual documents website is built and hosted for us by the Read The Docs project. Our RTD setup contains one main project for English and one additional project for each supported language added as translations to the main project. If you are a maintainer and want to add a language, first create a new project with manual import and set the language appropriately. Afterwards add this as a translation in the Admin page of the main project.