Соглашения

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

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

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

  • Файл ‣ Открыть

  • Открыть

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

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

    • Не используйте нумерацию строк в листингах короче 3-х строк.

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

Посмотрим на исходный код:
::

    Пример исходного кода

  1. Пользуйтесь нумерованными сносками (см. Сноски).

  2. Вставляйте изображения с помощью директивы .. figure:: (вместо .. image::), для масштабирования используйте параметр :scale:, а не :height: и :width (см. Масштабирование изображений в LaTeX).

  3. Добавляйте подписи к таблицам и рисункам (см. Изображения и иллюстрации и Таблицы).

  4. Делайте осмысленные комментарии к коммитам.

  5. В любой непонятной ситуации задавайте вопросы редактору, не импровизируйте.