Azure DevOps Wiki: управляйте документацией проекта и совместной работой
Azure DevOps имеет встроенную поддержку Wiki, что дает большую гибкость для документирования всего проекта из одного места. Было время, когда ваша документация представляла собой документ Microsoft Word на файловом сервере, и в большинстве случаев только автор мог запомнить его местонахождение и использовать. Используя Azure DevOps, мы можем контролировать весь проект, документировать, хранить файлы, отслеживать изменения, а также выполнять автоматическую сборку и выпуски на единой платформе, доступной в Интернете и работающей с вашими Windows, Linux и Mac. так же.
В вики Azure DevOps используется язык уценки, который был создан в 2004 году Джоном Грубером в сотрудничестве с Аароном Шварцем и использовался в GitHub и Azure DevOps.
Язык не является полным языком, направленным на замену HTML. Цель состояла в том, чтобы упростить написание и чтение, и есть некоторый синтаксис, который эмулирует наиболее распространенные теги HTML. Мы увидим несколько примеров языка уценки, после чего будем готовы создавать и форматировать нашу документацию.
Важно помнить об иерархии в Azure DevOps. У вас может быть несколько , и каждая организация может содержать несколько . У каждого отдельного проекта есть Wiki. Границы Wiki находятся на уровне проекта, а не организации. Имейте это в виду при планировании структуры документации.
Резюме языка уценки
Следующее резюме может помочь вам понять различия между и HTML. Начните вводить текст на вики-странице Azure DevOps, а поскольку вам понадобятся ресурсы для форматирования, проверьте приведенную ниже таблицу.
Вы будете быстро писать на языке уценки. Просто выделите некоторое время, чтобы запомнить символы, необходимые для форматирования текста.
| Вещь | эквивалент HTML | Язык уценки |
| Заголовок | <h1>Заголовок H1 </h1> | # Заголовок H1 |
| Заголовок* | <h2> Заголовок H2 </h2> | ## Заголовок H2 |
| Горизонтальная линия | <час> | <пустая строка> --- |
| Текст жирным шрифтом | <b> Текст выделен жирным шрифтом </b> | **Текст жирным** |
| Текст курсивом | <i> Текст курсивом </i> | *Текст курсивом* |
| Текст зачеркнут | <strike>Забастовка по тексту</strike> | ~~Забастовка по тексту~~ |
| Цитировать | – | > Цитата Уровень 1 |
| Цитировать | – | >> Цитата Уровень 2 (с отступом) |
| Ссылки | <a href=http://www.azure.microsoft.com>Портал Azure </a> | [Портал Azure] (http://www.azure.microsoft.com |
| Код | <code>Получить AzVM</code> | ““ <Язык необязательно><код> ““ |
| Изображение | <имг источник=http://address.ca/img.svg> |  |
| Неупорядоченный список | <ул> <li> Элемент 01</li> </ul> | – Пункт 01 |
| Упорядоченный список | <ол> <li>Элемент с номером 01 </li> </ол | 1. Пункт под номером 01 |
* Заголовок может достигать H6 в HTML, а в Markdown мы обозначаем его шестью ######
Мы рассмотрим подробности в Azure DevOps в нашем следующем разделе, но сейчас мы можем видеть слева код на языке уценки и то, как будет выводиться справа. Это будет опыт для пользователя, читающего документ.
Создание вашей первой вики Azure Devops
По умолчанию любой новый проект не имеет настроенной Wiki, и мы можем создать их двумя разными способами: WikiProject или Wiki as Code. Мы также можем комбинировать их, чтобы получить выгоду от обоих миров.
Давайте приступим к созданию WikiProject, который создает репозиторий Git для хранения всей информации о вики, включая файлы.md, изображения и т. д. Хотя это репозиторий, он скрыт от просмотра, а это означает, что вы не можете получить к нему доступ через репозитории или даже настройки проекта.
Если вам так же любопытно, как и мне, вы можете перейти на этот веб-сайт: https://dev.azure.com/<OrganizationName>/<ProjectName>/_git/<ProjectName>.wiki (элемент 1). Основная ветвь для этого репозитория называется (элемент 3), и мы можем видеть, что каждая отдельная страница, созданная через портал, представляет собой отдельный файл.md (элемент 2).
Примечание: на момент написания не существовало простого способа удалить WikiProject. Результатом будет редактор для создания новой страницы, где мы можем начать писать на нашем языке уценки, чтобы начать документацию нашего проекта.
Использование портала Azure DevOps для управления вашей вики очень просто. С левой стороны мы можем создать страницу с помощью кнопки Новая страница (Элемент 1), и новая страница будет добавлена на тот же уровень страниц, которые перечислены выше (родительский уровень).
Мы также можем создавать для существующей страницы, и это помогает размещать документацию в одном потоке. Для этого щелкните многоточие на нужной странице (пункт 2) и нажмите Добавить подстраницу (пункт 3).
В том же месте мы можем изменить порядок страниц, перетаскивая их по своему усмотрению.
Элемент «Обзор» дает представление о проекте, включая и краткое описание проекта, которое можно интегрировать с вики.
Интеграция проста в реализации. Выполните вход на портал Azure DevOps, щелкните Обзор, а затем кнопку + Добавить описание проекта. В новой колонке укажите краткое описание, выберите файл Readme или Wiki. В этом разделе мы собираемся выбрать Wiki (пункт 3), и появится первая страница (которая должна быть главной или страницей приветствия), нажмите «Сохранить» (пункт 4).
Отныне документация будет находиться на первой странице нашего портала Azure DevOps. Простое наглядное пособие, которое поможет вам запомнить, заключается в том, что первая страница всегда имеет связанный с ней значок .
Важное примечание: всегда будет отображаться первая страница вики. Если вы измените позже, изменение автоматически отразится на главной странице.
Добавление Wiki-as-a-code
По умолчанию при создании новых репозиториев опция добавления README.md определяется автоматически, и это файл, который может быть написан на так же, как мы настраиваем наши страницы в WikiProject.
Мы можем увидеть это в действии, взглянув на любой существующий репозиторий. На изображении ниже мы можем выбрать repo/README.md, чтобы документация всегда была актуальной.
Если команда решит обновить документацию на уровне репозитория, мы можем воспользоваться этим процессом и включить его в текущую вики.
Процесс добавления кода в качестве вики следующий: нажмите « Обзор » (элемент 1), «Вики» (элемент 2), щелкните раскрывающееся меню в <ProjectName>.wiki (элемент 3), а затем выберите «Опубликовать код как вики» (пункт 3). 4).
В новом блейде выберите , , папку (по умолчанию README.md находится в корне) и определите имя Wiki (мы будем использовать текущее имя репо, добавленное с суффиксом -Wiki). Нажмите «Опубликовать».
Когда мы открываем Wiki (элемент 1), мы можем перемещаться между WikiProject (элемент 2) или выбирать из Code Wiki, который был добавлен ранее (элемент 3). После выбора Code Wiki будут перечислены все файлы с расширением.md, нажмите на них, и содержимое отобразится с правой стороны.
Интегрируя оба метода, мы можем сделать WikiProject главной страницей вашего проекта и использовать фактический файл README.md в ваших репозиториях, чтобы получить более краткую и конкретную информацию о каждой рабочей нагрузке/службе вашего текущего проекта.
Azure DevOps Wiki: начало работы
Итак, теперь вы знаете основы языка уценки, как управлять страницами в вашей совершенно новой вики Azure DevOps и различать ее, а также как мы можем интегрировать вики-код и WikiProject.
Теперь ваша очередь начать интегрировать Wiki в ваш проект Azure DevOps!