Правила оформления документации

Эти рекомендации предлагают лучшие практики для улучшения документации и поддержания её организованной и легко доступной.

См. также написание документации.

Расположение и нумерация документов

Примечание: Эти руководства основаны на обсуждении, которое прошло в задаче #3349.

Документационная иерархия может быть значительно улучшена за счёт предоставления лучшей структуры и организации директорий.

Имея структурированную структуру документов, мы сможем иметь значимые URL, такие как docs.gitlab.com/user/project/merge_requests.html. С этим шаблоном вы сразу можете понять, что вы навигируете по документации для пользователей и она связана с проектом и его merge requests.

Таблица ниже показывает, какие виды документации находятся в каких директориях.| Директория | Что здесь находится | | --------- | -------------- | | doc/user/ | Документация для пользователей. Всё, что можно сделать в интерфейсе GitLab, находится здесь, включая /admin. | | doc/administration/ | Документация, которая требует доступа пользователя к серверу, где установлен GitLab. Настройки администратора, которые можно получить через интерфейс GitLab, находятся в директории doc/user/admin_area/. | | doc/api/ | Документация, связанная с API. | | doc/development/ | Документация, связанная с разработкой GitLab. Любые руководства по стилю должны находиться здесь. | | doc/legal/ | Юридические документы о вкладе в GitLab. | | doc/install/| Вероятно, самый посещаемый директорий, так как в нём находится installation.md. Идеально, чтобы он находился в директории doc/administration/, но лучше оставить его как есть, чтобы избежать путаницы (вопрос всё ещё обсуждается). | | doc/update/ | То же самое для doc/install/. Должен находиться в директории administration/, но это хорошо известное расположение, лучше оставить как есть, по крайней мере, на данный момент. | | doc/topics/ | Индексы по темам (doc/topics/topic-name/index.md): все ресурсы для этой темы (документация для пользователей и администраторов, статьи, и документация сторонних разработчиков). | | doc/articles/ | Технические статьи: руководства для пользователей, руководства для администраторов, технические обзоры, учебные пособия (doc/articles/article-title/index.md). |--- В разделе "Настройка сети" указаны параметры: "ip address" 192.168.1.1, "subnet mask" 255.255.255.0. Пожалуйста, убедитесь, что вы используете правильные значения для вашей сети.

В разделе "Настройка сети" указаны параметры: ip address 192.168.1.1, subnet mask 255.255.255.0. Пожалуйста, убедитесь, что вы используете правильные значения для вашей сети.

В разделе "Настройка сети" указаны параметры: IP-адрес 192.168.1.1, маска подсети 255.255.255.0. Пожалуйста, убедитесь, что вы используете правильные значения для вашей сети.

В разделе "Настройка сети" указаны параметры: IP-адрес 192.168.1.1**Общие правила:**1. Правильное наименование и расположение нового документа — это комбинация относительного URL документа и дизайна карты GitLab, используемого для целей UX (источник, изображение).

При создании нового документа и если его имя состоит из более чем одного слова, убедитесь, что вы используете подчеркивания вместо пробелов или дефисов (-). Например, правильное наименование будет import_projects_from_github.md. То же правило применяется к изображениям.
Существует четыре основных каталога: user, administration, api и development.
Каталог doc/user/ содержит пять основных подкаталогов: project/, group/, profile/, dashboard/ и admin_area/.
1. doc/user/project/ должен содержать всю документацию, связанную с проектами.
2. doc/user/group/ должен содержать всю документацию, связанную с группами.
3. doc/user/profile/ должен содержать всю документацию, связанную с профилями. Каждая страница, которую вы можете просмотреть по пути /profile, должна иметь свой собственный документ, например, account.md, applications.md, emails.md и т. д.
4. doc/user/dashboard/ должен содержать всю документацию, связанную с панелями управления.
5. doc/user/admin_area/ должен содержать всю документацию, связанную с администрированием, описывая, что можно достичь, используя интерфейс администрирования GitLab (не путать с doc/administration, где требуется доступ к серверу). 1.Каждая категория по пути /admin/application_settings должна иметь свой собственный документ, расположенный по пути doc/user/admin_area/settings/. Например, категория Visibility and Access Controls должна иметь документ, расположенный по пути doc/user/admin_area/settings/visibility_and_access_controls.md.
Каталог doc/topics/ содержит технический контент, связанный с темами. Создайте doc/topics/topic-name/subtopic-name/index.md, когда подтемы становятся необходимыми. Общая документация, связанная с пользователями и администрированием, должна быть расположена соответствующим образом.
Для технических статей размещайте их изображения в каталоге doc/articles/article-title/img/.Если вы не уверены, где должен находиться документ, вы можете обратиться к @axil в вашем запросе на слияние.

Текст

Разделите длинные строки, это значительно упрощает их просмотр и редактирование. Только двойные переносы строк отображаются как полные переносы строк в GitLab markdown. Длина строки в 80-100 символов считается хорошей.
Убедитесь, что документация добавлена в правильную директорию и что есть ссылка на неё в удобном месте.
Не дублируйте информацию.
Будьте краткими и ясными.
Если нет логического основания для этого, добавляйте документы в алфавитном порядке.
Пишите на американском английском.
Используйте [одинарные пробелы][] вместо двойных пробелов.

Форматирование

Используйте дефисы (-) для неупорядоченных списков вместо звёздочек (*).
Используйте цифру один (1) для упорядоченных списков.
Используйте подчёркивания (_) для выделения слова или текста курсивом.
Используйте двойные звёздочки (**) для выделения слова или текста жирным шрифтом.
При использовании списков, лучше не заканчивайте каждый элемент точкой. Вы можете использовать их, если есть несколько предложений, просто оставьте последнее предложение без точки.

Заголовки# Правила оформления документации

Добавьте только один заголовок H1 в каждом документе, добавив `#` в начале (при использовании markdown). Для подзаголовков используйте `##`, `###` и так далее.

Избегайте использования чисел в заголовках. Числа смещаются, следовательно, смещаются и ссылки на документы, что в конечном итоге приводит к появлению неактивных ссылок. Если вы считаете, что необходимо добавить числа в заголовки, убедитесь, что вы обсудите это с кем-то в запросе на слияние.

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

При создании нового документа будьте осторожны, чтобы заголовки были грамматически и синтаксически корректными. Рекомендуется обратиться для проверки к одному или нескольким из следующих членов команды GitLab: `@axil`, `@rspeicher`, `@marcia`, `@SeanPackham`. Это для того, чтобы убедиться, что ни один документ с некорректными заголовками не будет опубликован без проверки, что предотвращает появление неактивных ссылок и проблем с перенаправлением при исправлении.

Оставьте ровно один перенос строки после заголовка## Ссылки

Если ссылка делает абзац многократно разрывающимся на несколько строк, не используйте обычный подход Markdown: [Text](https://example.com). Вместо этого используйте [Text][identifier] и в самом низу документа добавьте: [identifier]: https://example.com. Это еще один способ создания ссылок в Markdown, который сохраняет документ ясным и кратким. Дополнительные баллы, если вы также добавите альтернативный текст: [identifier]: https://example.com "Альтернативный текст", который появляется при наведении указателя мыши на ссылку.

Ссылки на встроенные документы

Иногда требуется создать ссылку на встроенные документы, которые GitLab предоставляет в директории /help. Это обычно делается в файлах внутри директории app/views/ с помощью вспомогательного метода help_page_path.

В самом простом виде HAML-код для создания ссылки на страницу /help выглядит следующим образом:

= link_to 'Help page', help_page_path('user/permissions')

Метод help_page_path содержит путь к документу, на который вы хотите создать ссылку, с следующими соглашениями:

путь является относительным к директории doc/ в репозитории GitLab
расширение .md должно быть опущено
путь не должен заканчиваться слешем (/)

Ниже приведены некоторые специальные случаи, когда следует использовать метод help_page_path в зависимости от контекста. Вы можете комбинировать один или несколько из следующих:1. Ссылка на якорь. Используйте anchor как часть метода help_page_path:

```haml
= link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
```

Открытие ссылок в новой вкладке. Это должно быть стандартным поведением:
```
= link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
```
Ссылка на круглый значок. Обычно используется в настройках, где длинное описание не может быть использовано, например, рядом с флажками. Вы можете использовать любой значок Font Awesome, но предпочтительно использовать question-circle:
```
= link_to icon('question-circle'), help_page_path('user/permissions')
```
Использование кнопки-ссылки. Полезно в местах, где текст выходит из контекста остальной части разметки страницы:
```
= link_to 'Help page', help_page_path('user/permissions'), class: 'btn btn-info'
```

Подчеркивание ссылки.

= link_to 'Help page', help_page_path('user/permissions'), class: 'underlined-link'

Использование ссылок в тексте.

Описание к #{link_to 'Help page', help_page_path('user/permissions')}.

Добавление точки в конце предложения. Полезно, когда вы не хотите, чтобы точка была частью ссылки:

= succeed '.' do
  Узнайте больше на странице
  = link_to 'Help page', help_page_path('user/permissions')
```## Изображения — Размещайте изображения в отдельной директории с именем `img/` в той же директории, где находится ваш документ `.md`. Всегда добавляйте в начало имен изображений имя документа, в который они будут включены. Например, если есть документ с именем `twitter.md`, то допустимым именем изображения может быть `twitter_login_screen.png`. [**Исключение**: изображения для [статей](writing_documentation.md#technical-articles) следует размещать в директории `img` под `/articles/article_title/img/`, поэтому нет необходимости добавлять имя документа в начало имен файлов.]

Изображения должны иметь конкретное, а не общее имя, которое будет их различать.
Сохраняйте все имена файлов в нижнем регистре.
Рассмотрите возможность использования изображений в формате PNG вместо JPEG.
Сжимайте все изображения с помощью https://tinypng.com/ или подобного инструмента.
Сжимайте анимированные изображения в формате GIF с помощью https://ezgif.com/optimize или подобного инструмента.
Изображения следует использовать (только когда это необходимо) для иллюстрации описания процесса, а не для замены его.- Markdown-способ вставки изображения в документ: ![Правильное описание, что изображение означает](img/document_image_title.png)
Всегда используйте правильное описание, что изображение означает. Таким образом, когда браузер не может показать изображение, этот текст будет использоваться как альтернативное описание.
Если есть последовательные изображения с небольшим количеством текста между ними, всегда добавляйте три дефиса (---) между изображением и текстом для создания горизонтальной линии для лучшей читаемости.
Если заголовок помещается сразу после изображения, всегда добавляйте три дефиса (---) между изображением и заголовком.

Примечания

Примечания должны быть выделены словом Note: жирным шрифтом. Используйте этот формат:
```
>**Note:**
Это что-то, что следует отметить.
```
что отображается как:

Note: Это что-то, что следует отметить.

Если примечание занимает несколько строк, это допустимо.

Новые функции

Каждый документ, связанный с новой функцией, должен объявлять версию GitLab, в которой эта функция была введена. Немного ниже заголовка добавьте примечание:
```
> Введено в GitLab 8.3.
```
Если возможно, каждая функция должна иметь ссылку на MR, который её ввёл. Вышеупомянутое примечание будет преобразовано к следующему: ```

Введено в GitLab 8.3.
```
, где идентификатор ссылки назван в соответствии с репозиторием (CE) и номером MR.
```
Если функция доступна только в GitLab Enterprise Edition, не забудьте об этом упомянуть, как:
```
> Введено в GitLab Enterprise Edition 8.3.
```
В противном случае, упоминание можно опустить.

Ссылки

Перезапуск GitLab: Существует множество случаев, когда требуется перезапуск или переконфигурирование GitLab. Чтобы избежать дублирования, ссылайтесь на специальный документ, который можно найти в doc/administration/restart_gitlab.md. Обычно текст будет выглядеть следующим образом:
```
Сохраните файл и [перезапустите GitLab](../administration/restart_gitlab.md)
для применения изменений.
```
Если документ, который вы редактируете, находится в другом месте, отличном от директории doc/ GitLab CE/EE, вместо относительной ссылки используйте полный путь: http://docs.gitlab.com/ce/administration/restart_gitlab.html. Замените переконфигурирование на перезапуск там, где это необходимо.

Инструкция по установке

Ruby: В шаге 2 инструкции по установке мы устанавливаем Ruby из исходного кода. При появлении новой версии, которую нужно обновить, не забудьте изменить её в блоке кода и заменить sha256sum (он может быть найден на [странице загрузки][ruby-dl] сайта Ruby).[ruby-dl]: https://www.ruby-lang.org/en/downloads/ "Сайт загрузки Ruby"

Изменение местоположения документа

Изменение местоположения документа не должно быть произвольным. Помните, что документация доступна для всех установок под help/ и не только для GitLab.com или http://docs.gitlab.com. Убедитесь, что это обсуждено с командой документации заранее.

Если вам действительно нужно изменить местоположение документа, не удаляйте старый документ, а вместо этого добавьте текст, указывающий на новое местоположение, например:

Этот документ был перемещён в [path/to/new_doc.md](path/to/new_doc.md).

где path/to/new_doc.md — относительный путь к корневому каталогу doc/.

Например, если вы хотите переместить doc/workflow/lfs/lfs_administration.md в doc/administration/lfs.md, то шаги будут следующими:

Скопируйте doc/workflow/lfs/lfs_administration.md в doc/administration/lfs.md

Замените содержимое doc/workflow/lfs/lfs_administration.md на:

Этот документ был перемещён в [administration/lfs.md](../../administration/lfs.md).

Найдите и замените все вхождения старого местоположения на новое. Быстрым способом для поиска является использование git grep. Сначала перейдите в корневой каталог, где вы клонировали репозиторий gitlab-ce, а затем выполните:
```
git grep -n "workflow/lfs/lfs_administration"
git grep -n "lfs/lfs_administration"
```Важные моменты:
```

Поскольку мы также используем встроенные комментарии к коду, помимо документации, документ может ссылаться на него в представлениях GitLab (app/), которые отображаются при посещении /help, а также иногда в тестовом наборе (spec/).
Вышеупомянутая команда git grep будет рекурсивно искать в директории, в которой она запущена, строки с workflow/lfs/lfs_administration и lfs/lfs_administration и будет выводить файл и строку, где упоминается этот файл. Вы можете спросить, почему используется два поиска. Поскольку мы используем относительные пути для ссылок на документацию, иногда полезно искать путь глубже.
Расширение *.md не используется, когда документ ссылается на встроенные страницы справки GitLab, поэтому мы его опускаем в git grep.

Конфигурационная документация для установок из исходников и с использованием Omnibus-пакетовGitLab официально поддерживает два метода установки: установки из исходников и установки с использованием Omnibus-пакетов.

Когда есть настройки, которые можно настроить для обоих методов установки, рекомендуется документировать их в документации CE, чтобы избежать дублирования.

Настройки конфигурации включают:

настройки, которые затрагивают конфигурационные файлы в config/
настройки NGINX и настройки в lib/support/ в целом

Когда есть список шагов для выполнения, обычно это означает редактирование конфигурационного файла и переконфигурирование/перезапуск GitLab. В этом случае следует следовать стилю ниже в качестве руководства:

**Для установок с использованием Omnibus**

1. Редактируйте `/etc/gitlab/gitlab.rb`:

    ```ruby
    external_url "https://gitlab.example.com"
    ```

1. Сохраните файл и [переконфигурируйте] GitLab для применения изменений.

---

**Для установок из исходников**

1. Редактируйте `config/gitlab.yml`:

    ```yaml
    gitlab:
      host: "gitlab.example.com"
    ```

1. Сохраните файл и [перезапустите] GitLab для применения изменений.


[переконфигурируйте]: path/to/administration/gitlab_restart.md#omnibus-gitlab-reconfigure
[перезапустите]: path/to/administration/gitlab_restart.md#installations-from-source

В этом случае:- перед каждым шагом метод установки объявляется жирным шрифтом

три дефиса (---) используются для создания горизонтальной линии и разделения двух методов
блоки кода отступаются на один или более пробелов под элементом списка для правильного отображения
разные языки выделения используются для каждого конфига в блоке кода
ссылки используются для переконфигурирования/перезапуска## Фейковые токены

Возможно, вам потребуется токен для демонстрации вызова API с использованием cURL или секретного переменного, используемого в CI. Рекомендуется не использовать реальные токены в документации, даже если вероятность эксплуатации токена низкая.

Вы можете использовать следующие фейковые токены в качестве примеров.

Тип токена	Значение токена
Частный токен пользователя	`9koXpg98eAheJpvBs5tK`
Токен доступа пользователя	`n671WNGecHugsdEDPsyo`
ID приложения	`2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6`
Секрет приложения	`04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df`
Секретная переменная CI	`Li8j-mLUVA3eZYjPfd_H`
Токен конкретного запуска	`yrnZW46BrtBFqM7xDzE7dddd`
Токен общего запуска	`6Vk7ZsosqQyfreAxXTZr`
Токен триггера	`be20d8dcc028677c931e04f3871a9b`
Секретный токен вебхука	`6XhDroRcYPM5by_h-HLY`
Токен проверки состояния	`Tu7BgjR9qeZTEyRzGG2P`
Токен профиля запроса	`7VgpS4Ax5utVD2esNstz`

API

Вот список обязательных элементов. Используйте их в точном порядке, в котором они указаны в этом документе. Дополнительное объяснение дано ниже.

Каждый метод должен иметь запрос REST API. Например:

GET /projects/:id/repository/branches
```- Каждый метод должен иметь подробное описание параметров ([см. описание метода](#описание-метода)).

Каждый метод должен иметь пример cURL.
Каждый метод должен иметь тело ответа (в формате JSON).### Описание метода

Используйте следующие заголовки таблицы для описания методов. Атрибуты всегда должны быть в блоках кода с использованием обратных апострофов (`).

| Атрибут | Тип | Обязательный | Описание |
| -------- | ---- | ----------- | -------- |

Пример отображения:

Атрибут	Тип	Обязательный	Описание
`user`	string	да	Имя пользователя GitLab

Команды cURL

Используйте https://gitlab.example.com/api/v4/ в качестве конечной точки.
Везде, где это необходимо, используйте этот приватный токен: 9koXpg98eAheJpvBs5tK.
Всегда ставьте запрос первым. GET является по умолчанию, поэтому его не нужно включать.
Используйте двойные кавычки для URL, когда он включает дополнительные параметры.
Предпочтительно использовать примеры с использованием приватного токена и не передавать данные имени пользователя и пароля.

Методы	Описание
`-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"`	Используйте этот метод в таком виде, когда требуется аутентификация
`-X POST`	Используйте этот метод при создании новых объектов
`-X PUT`	Используйте этот метод при обновлении существующих объектов
`-X DELETE`	Используйте этот метод при удалении существующих объектов

Примеры cURL

Ниже приведен набор примеров cURL, которые можно использовать в документации API.#### Простая команда cURL

Получить детали группы:

curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/gitlab-org

Пример cURL с параметрами, переданными в URL

Создать новый проект в пространстве имен аутентифицированного пользователя:

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects?name=foo"

Передача данных с помощью cURL --data

Вместо использования -X POST и добавления параметров к URI можно использовать опцию --data cURL. Пример ниже создаст новый проект foo в пространстве имен аутентифицированного пользователя.

curl --data "name=foo" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"

Отправка данных с использованием JSON-контента

Примечание: В этом примере мы создаем новую группу. Обратите внимание на использование одинарных и двойных кавычек.

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups

Отправка данных с использованием form-data

Вместо использования JSON или urlencode вы можете использовать multipart/form-data, что правильно обрабатывает кодировку данных:

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v4/users/25/keys

Приведенный выше пример выполняется администратором и добавляет публичный ключ SSH с названием ssh-key в аккаунт пользователя, имеющего идентификатор 25.#### Экранирование специальных символов

Пробелы или слеши (/) могут иногда приводить к ошибкам, поэтому рекомендуется экранировать их, когда это возможно. В примере ниже мы создаем новую задачу, в которой в заголовке присутствуют пробелы. Обратите внимание, как пробелы экранируются с помощью ASCII-кода %20.

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"

Используйте %2F для слешей (/).

Передача массивов в вызовах API

API GitLab иногда принимает массивы строк или целых чисел. Например, чтобы ограничить домены электронной почты для регистрации в экземпляре GitLab только *.example.com и example.net, вы можете сделать что-то вроде этого:

curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings

OSCHINA-MIRROR/panda26-gitlab

Правила оформления документации

Расположение и нумерация документов

Текст

Форматирование

Заголовки# Правила оформления документации

Добавьте только один заголовок H1 в каждом документе, добавив `#` в начале (при использовании markdown). Для подзаголовков используйте `##`, `###` и так далее.

Оставьте ровно один перенос строки после заголовка## Ссылки

Ссылки на встроенные документы

Примечания

Новые функции

Ссылки

Инструкция по установке

Изменение местоположения документа

API

Команды cURL

Примеры cURL

Пример cURL с параметрами, переданными в URL

Передача данных с помощью cURL --data

Отправка данных с использованием JSON-контента

Отправка данных с использованием form-data

Передача массивов в вызовах API

Опубликовать ( 0 )

Введение

Обновления

Участники

Язык

Недавние действия

OSCHINA-MIRROR/panda26-gitlab .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Правила оформления документации

Расположение и нумерация документов

Текст

Форматирование

Заголовки# Правила оформления документации

Добавьте только один заголовок H1 в каждом документе, добавив # в начале (при использовании markdown). Для подзаголовков используйте ##, ### и так далее.

Оставьте ровно один перенос строки после заголовка## Ссылки

Ссылки на встроенные документы

Примечания

Новые функции

Ссылки

Инструкция по установке

Изменение местоположения документа

API

Команды cURL

Примеры cURL

Пример cURL с параметрами, переданными в URL

Передача данных с помощью cURL --data

Отправка данных с использованием JSON-контента

Отправка данных с использованием form-data

Передача массивов в вызовах API

Опубликовать ( 0 )

Введение

Обновления

Участники

Язык

Недавние действия

OSCHINA-MIRROR/panda26-gitlab

Добавьте только один заголовок H1 в каждом документе, добавив `#` в начале (при использовании markdown). Для подзаголовков используйте `##`, `###` и так далее.