Рекомендации по написанию документации

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

Вопросы по разметке

Перенос текста

Строка ограничена 80 символами для обычного текста и никак не ограничена для любых других конструкций, когда обтекание влияет на читаемость ReST и / или HTML-вывод. Кроме того, нет смысла переносить текст в строках короче 80 символов, если у вас для этого нет веских оснований.

Ограничение в 80 символов исходит из разрешения экрана ISO/ANSI 80x24, и маловероятно, что читатели/писатели будут использовать 80-символьные консоли. Тем не менее, такое ограничение по-прежнему является стандартом во многих рекомендациях по программированию (включая Tarantool). Что касается писателей, то благодаря ограничению размера страницы окно с текстом может быть довольно узким, оставляя больше места для других приложений в широкоэкранном окружении.

Форматирование фрагментов кода

Для фрагментов коды мы обычно используем директиву code-block с соответствующей подсветкой синтаксиса языка. Чаще всего используем следующее:

.. code-block:: tarantoolsession

.. code-block:: console

.. code-block:: lua

Например (фрагмент Lua-кода):

for page in paged_iter("X", 10) do
  print("New Page. Number Of Tuples = " .. #page)
  for i=1,#page,1 do print(page[i]) end
end

В редких случаях при необходимости подсветить отдельные части фрагмента кода, когда директивы code-block недостаточно, мы используем директиву codenormal построчно вместе с явным форматированием вывода (как указано в doc/sphinx/_static/sphinx_design.css).

Примеры:

Синтаксис функции (объект-заполнитель имя-спейса отображается курсивом):

box.space.имя-спейса:create_index(„index-name“)
Сессия tdb (ввод информации пользователем выделяется жирным шрифтом, приглашение на ввод команды – синим, вывод – зеленым):
```
$ tarantool example.lua
(TDB)  Tarantool debugger v.0.0.3. Type h for help
example.lua
(TDB)  [example.lua]
(TDB)  3: i = 1
```

Внимание: Каждая запись с явным форматированием вывода (codenormal, codebold и т.п.) часто вызывает трудности при переводе документации на другие языки. Постарайтесь избегать специального форматирования, если только без него никак НЕЛЬЗЯ обойтись.

Использование разделенных ссылок

Избегайте разделения ссылки и определения цели (ref), например:

Это абзац, который содержит `ссылку`_.

 .. ссылка: http://example.com/

Используйте неразделенные ссылки:

Это абзац, который содержит `ссылку <http://example.com/>`_.

Внимание: Каждая разделенная ссылка часто вызывает трудности при переводе документации на другие языки. Постарайтесь избегать разделенных ссылок, если только без них никак НЕЛЬЗЯ обойтись (например, в таблицах).

Создание меток для локальных ссылок

Мы стараемся не использовать автоматически сгенерированные sphinx ссылки для большинства объектов. Вместо них мы добавляем собственные метки для ссылок на любое место в документации.

Соглашение об именовании заключается в следующем:

Набор символов: от a до z, от 0 до 9, дефис, подчеркивание.
Формат: путь дефис имя файла дефис тег

Пример: _c_api-box_index-iterator_type
где:
c_api – имя директории,
box_index – имя файла (без «.rst»), а
iterator_type – тег.

Имя файла используется для того, чтобы понять, куда указывает «ref». И если имя файла имеет смысл, это гораздо понятнее.

Имени файла без пути достаточно, когда оно уникально в пределах doc/sphinx. Поэтому для файла fiber.rst достаточно будет «fiber», а не «reference-fiber». Тогда как для «index.rst» (а у нас множество файлов «index.rst» в разных директориях) необходимо указать путь до имени файла, например, «reference-index».

Используйте дефис «-«, чтобы разграничить путь и имя файла. В исходном коде документации мы пользуемся только символами подчеркивания «_» при указании пути и имени файла, оставляя дефисы «-» для разграничения в локальных ссылках.

Тег может содержать любую значимую информацию. Единственная рекомендация дается для элементов синтаксиса Tarantool’а, где предпочтительно использовать следующий синтаксис в тегах: имя_объекта_или_модуля дефис имя_элемента. Например, box_space-drop.

Добавление комментариев

Иногда могут потребоваться комментарии в файле ReST. Чтобы sphinx не учитывал этот текст во время обработки, используйте следующую запись в каждой строке в качестве маркера комментария («.. //»):

.. // здесь комментарий

Начальные символы «.. //» не пересекаются с другими символами разметки ReST, и их легко обнаружить как визуально, так и с помощью grep. В поиске grep нет символов, которые нужно избегать, просто выполните примерно следующее:

$ grep ".. //" doc/sphinx/dev_guide/*.rst

Тем не менее, эти комментарии не сработают должным образом во вложенной документации (например, если оставить комментарий в модуле -> объекте -> методе, sphinx игнорирует комментарий и всё вложенное содержимое, который следует в описании метода).

Вопросы по стилю и языку

Британский или американский вариант английского

В английской версии документации мы придерживаемся американского варианта английского языка.

Экземпляр или сервер

Ссылаясь на экземпляр Tarantool-сервера, мы говорим «экземпляр», а не «сервер». Это обеспечивает однородность терминологии в руководстве и именами в окружении Tarantool’а (например, /etc/tarantool/instances.enabled – активные экземпляры).

Неправильно: «С помощью репликации несколько серверов Tarantool’а могут работать на копиях одинаковых баз данных.»

Правильно: «С помощью репликации несколько экземпляров Tarantool’а могут работать на копиях одинаковых баз данных.»

Примеры и шаблоны

Модуль и функция

Ниже приводится пример документирования модуля (my_fiber) и функции (my_fiber.create).

my_fiber.create(function[, function-arguments])

Создание и запуск my_fiber. Происходит создание объекта, который незамедлительно начинает работу.

тип возвращаемого значения:
Параметры:	function – функция, которая будет связана с `my_fiber` function-arguments – что передается в функцию
возвращает:	созданный объект `my_fiber`
	пользовательские данные

Пример:

tarantool> my_fiber = require('my_fiber')
---
...
tarantool> function function_name()
         >   my_fiber.sleep(1000)
         > end
---
...
tarantool> my_fiber_object = my_fiber.create(function_name)
---
...

Модуль, класс и метод

Ниже приводится пример документирования модуля (my_box.index), класса (my_index_object) и функции (my_index_object.rename).

object my_index_object

my_index_object:rename(index-name)

Переименование индекса.

Параметры:	index_object – ссылка на объект index_name – новое имя для индекса (тип = строка)
возвращает:	nil

Возможные ошибки: index_object не существует.