Соглашения

Данный раздел касается тех проектов, в которых я задействован. Здесь приведены некоторые общие соглашения и рекомендации относительно оформления документации.

1. Для обозначения пунктов меню используйте команды menuselection и guilabel.

:menuselection:`&Файл --> &Открыть`
:guilabel:`&Открыть`
  • Файл ‣ Открыть
  • Открыть

Символ & устанавливает в зависити от темы HTML следующему за ним символу нижнее подчеркивание. Обязательно сверяйтесь с подчеркиваниями в пунктах меню программы.

  1. Для примеров исходного кода на различных языках программирования, используйте конструкцию .. code-block:: (см. Примеры исходного кода с подсветкой синтаксиса).

    • Не используйте нумерацию строк в листингах короче 3-х строк.
    • Для листингов не примеров исходного кода на языках программирования допускается использовать более простую конструкцию :: (см. Листинги (исходный код)). При этом лучше использовать более явный стиль команды ::, когда она располагается на новой строке:
Посмотрим на исходный код:
::

    Пример исходного кода
  1. Пользуйтесь нумерованными сносками (см. Сноски).
  2. Вставляйте изображения с помощью директивы .. figure:: (вместо .. image::), для масштабирования используйте параметр :scale:, а не :height: и :width (см. Масштабирование изображений в LaTeX).
  3. Добавляйте подписи к таблицам и рисункам (см. Изображения и иллюстрации и Таблицы).
  4. Делайте осмысленные комментарии к коммитам.
  5. В любой непонятной ситуации задавайте вопросы редактору, не импровизируйте.