Рекомендации по написанию документации
Данные рекомендации обновляются по запросу, охватывая только те проблемы, которые вызывают вопросы у авторов документации. На данный момент мы не стремимся разработать исчерпывающее руководство по написанию документации для проекта 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) --- ...
- function – функция, которая будет связана с
Ниже приводится пример документирования модуля (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 не существует.
Пример:
tarantool> box.space.space55.index.primary:rename('secondary') --- ...
Факторы сложности: Размер индекса, тип индекса, количество кортежей, к которым получен доступ.
-