Unity 6.3
0 онлайн 8 гостей 3 в системе
Вход
← Руководство

Документация вашего пакета

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

Когда вы создаёте пакет с помощью окна Package Manager, Unity Editor создаёт папку Documentation в базовой папке вашего пакета. Эта папка содержит один файл в формате Markdown, чьи легкий синтаксис используется на многих платформах, таких как GitHub и Bitbucket. Этот предоставленный файл Markdown содержит замещающее содержимое и инструкции, которые помогут вам создать первый черновик вашего набора документации.

До тех пор, пока у вас есть содержимое Markdown в папке Documentation вашего пакета, макет, который вы выбираете, является свободной формой и гибким. Вы можете написать свою документацию в одном файле, предоставленном или вы можете создать более сложную структуру через несколько файлов. Вы можете даже создать документацию в HTML и разместить ее на своем собственном сайте.

После того, как пользователи установят пакет, они смогут получить доступ к его документации с помощью Документация ссылка в панель деталей от Unity’s Package Manager Если документация не размещена на внешнем сервере, пользователи могут щелкнуть правой кнопкой мыши документацию и выбрать «Открыть документацию», чтобы открыть документацию на основе свойства, установленного в файле манифеста пакета. Документация ссылка для просмотра локальной версии документации в вашем пакете Documentation папка.

Чтобы задокументировать пакет:

  1. Перейдите в папку Documentation в базовой папке пакета.

  2. Откройте файл Markdown в выбранном вами редакторе скриптов.

  3. Следуйте встроенным инструкциям в файле, заменяя содержимое замены своим собственным. По желанию форматируйте информацию с помощью Markdown. Рекомендуемые разделы:

    • О: Краткое, высокоуровневое объяснение пакета.
    • Установка: Вы можете обратиться к официальным инструкциям по установке Package Manager, но если у вас есть какие-либо особые требования к установке, такие как установка образцов, добавьте их здесь.
    • Потребности в ресурсах: Это хорошее место для добавления требований к оборудованию или программному обеспечению, включая версии Unity Editor этот пакет совместим с.
    • Использование: Информация, объясняющая, как использовать пакет. Точное содержание использования зависит от типа пакета. Однако содержание использования может включать такие вещи, как процедуры, справочная информация, объясняющая свойства и настройки, и многое другое.
    • Известные ограничения: Если у этой версии вашего пакета есть какие-либо нетривиальные ограничения, перечислите их здесь.
    • Содержимое пакета: Включите расположение важных файлов, о которых вы хотите, чтобы пользователь знал. Например, если это образцовый пакет, содержащий текстуры, модели и материалы, разделенные группами образцов, вы можете указать расположение папки каждой группы.
    • История ревизий документа: Отслеживание, когда вы создаете и обновляете документацию. Рассмотрим таблицу со столбцами даты и описания.

  4. Сохраните файл.

  5. (Необязательно) Если вы хотите разместить документацию на своем собственном веб-сайте, преобразуйте Markdown в HTML, затем отредактируйте манифест пакета, установив свойство documentationUrl. Установите его значение на URL, где вы будете размещать документацию.

По мере развития вашего пакета, подумайте о добавлении большего количества разделов в вашу документацию. Следующие разделы являются только предложениями, но представляют типы содержания, которое может содержать качественная документация.

Секция Описание
Рабочие процессы Включите список действий, которые пользователь может выполнить, чтобы продемонстрировать, как использовать функцию. Вы можете включить скриншоты, чтобы помочь описать, как использовать функцию.
Продвинутые темы Подробная информация о том, что вы предоставляете пользователям. Это идеально, если вы не хотите перегружать пользователя слишком много информации заранее.
Справочник Если у вашего интерфейса много свойств, их подробности удобно вынести в справочный раздел. Хороший способ дать описания конкретных свойств — таблицы.
Образцы Для пакетов, содержащих образцовые файлы, вы можете включить подробную информацию о том, как пользователь может использовать эти образцовые файлы в своих проектах и сценах.
Учебники Если вы хотите предложить пошаговые инструкции по сложным процедурам, вы также можете добавить их здесь. Используйте пошаговые инструкции и включайте изображения, если они помогают пользователю понять.
Обратная связь и поддержка Дайте ссылки на получение помощи и отправку отзывов: публичные форумы или базы знаний и контакты поддержки.

Ознакомьтесь с документацией пакета для собственных пакетов , выпущенных Unity для идей и вдохновения.

Перед тем, как поделиться пакетом

Обычно разработчикам, устанавливающим ваш пакет, не нужно импортировать файлы документации в проект. Рекомендуется использовать окно Project, чтобы переименовать папку Documentation в вашем пакете в Documentation~, прежде чем вы экспортируете или для совместного использования с. Переименованная папка исчезает из редактора, но по-прежнему существует на диске. Тилда (~) гарантирует, что документация не добавляется непосредственно в проект. Разработчики, использующие ваш пакет, могут просматривать вашу документацию со ссылки Документация в окне Package Manager.

Важная: Используйте Project окно, чтобы переименовать папку, вместо того, чтобы использовать приложение управления файлами для прямого переименования папки на диске.

Дополнительные ресурсы