Документация для Unity asset

Зачем использовать такой формат

Такой формат позволяет упаковать документацию вместе с Unity asset в виде одного HTML-файла, который открывается локально, не требует отдельной папки со стилями и скриптами, подходит для Asset Store-пакета, внутренней доставки клиентам и офлайн-использования внутри Unity-проекта.

Быстрая точка входа с Asset Doc Wizard

Asset Doc Wizard — бесплатный Unity asset для быстрого создания оформленной точки входа в локальную HTML-документацию. Его визуальный мастер помогает связать документацию с Unity asset, настроить логотип, название, версию и описание, добавить ссылки на сайт и поддержку, а затем открывать HTML-файл во внешнем браузере.

Если нужен полностью ручной вариант, ниже показано, как реализовать его с помощью ScriptableObject и custom inspector.

Как спланировать структуру

Удобно сначала набросать структуру документации, а затем уже собирать итоговый HTML. Для Unity asset часто используют несколько отдельных страниц с разными задачами.

Например, структура может быть такой:

• Overview или What is this asset с коротким описанием пользы и основных возможностей.
• Quick Start с самым коротким путем от импорта пакета до первого рабочего результата.
• Setup с зависимостями, требованиями к сцене, настройками inspector и обязательными шагами после импорта.
• Examples с разбором типовых сценариев: базовое использование, частые интеграции, расширение поведения.
• Troubleshooting с типовыми ошибками, пустой сценой, missing references, неправильной конфигурацией и способами проверки.
• Release Notes или Migration, если asset обновляется и пользователям важно переносить проект между версиями.
• API Reference, если у asset есть значимая публичная C#-поверхность.

Пример структуры для Unity asset может выглядеть так:

Documentation
├─ Overview
├─ Quick Start
├─ Setup
├─ Examples
│  ├─ Basic Example
│  ├─ Runtime Example
│  └─ Editor Example
├─ Troubleshooting
├─ Migration
└─ API Reference

Как разложить файлы в пакете

После этого экспортируйте документацию в один HTML-файл и положите его внутрь самого asset-пакета. Практический шаблон раскладки может быть таким:

.../Your Asset/
├─ Documentation/
│  ├─ Documentation.asset
│  └─ Content/
│     └─ Documentation-Content.html
├─ Scripts/
│  ├─ Documentation/
│  │  └─ Documentation.cs
│  └─ Editor/
│     └─ Editors/
│        └─ DocumentationEditor.cs

Если у вас уже есть конкретный проект, итоговые пути могут быть любыми. Например, HTML можно хранить в файле вроде Documentation/Content/Documentation-Content.html, а Documentation.asset использовать как отдельную точку входа в локальную документацию. Такой вариант удобен тем, что сам HTML остается внутри служебной папки, а пользователь открывает документацию через asset или editor-кнопку.

Один из удобных вариантов связки файлов выглядит так:

• Documentation-Content.html — сам экспортированный документ One File Docs.
• Documentation.cs — ScriptableObject, который служит точкой входа в документацию.
• DocumentationEditor.cs — custom inspector с кнопкой открытия локальной документации.
• Documentation.asset — готовый asset, который пользователь может выбрать в Project window и сразу открыть документацию из Inspector.

Такой подход делает документацию частью пакета. После импорта asset пользователь может выбрать Documentation.asset в Project window и открыть локальный HTML прямо из Inspector.

Как открывать HTML в Unity Editor

В Unity Editor пользователь не сможет открыть HTML-файл напрямую из Inspector как обычный встроенный preview. Поэтому локальную документацию обычно открывают программно: кнопкой в custom inspector, пунктом меню или отдельным editor window action.

Пример Documentation.cs

using UnityEngine;

namespace MyAsset
{
    [CreateAssetMenu(fileName = "Documentation", menuName = "MyAsset Documentation/Documentation")]
    public class Documentation : ScriptableObject
    {
        // This class can stay empty.
        // It only connects Documentation.asset
        // with the custom inspector in DocumentationEditor.cs.
    }
}

Пример DocumentationEditor.cs

using System;
using System.IO;
using UnityEditor;
using UnityEngine;

namespace MyAsset
{
    [CustomEditor(typeof(Documentation))]
    public class DocumentationEditor : Editor
    {
        public override void OnInspectorGUI()
        {
            DrawDefaultInspector();

            if (GUILayout.Button("Open Documentation"))
            {
                string assetPath = AssetDatabase.GetAssetPath(target);
                string assetDirectory = Path.GetDirectoryName(assetPath);
                string fullPath = Path.GetFullPath(Path.Combine(assetDirectory, "../Documentation/Content/Documentation-Content.html"));

                if (!File.Exists(fullPath))
                {
                    Debug.LogWarning("Documentation file not found: " + fullPath);
                    return;
                }

                Application.OpenURL(new Uri(fullPath).AbsoluteUri);
            }
        }
    }
}

Как это работает для пользователя

В таком варианте Documentation.asset становится точкой входа, а открытие локального HTML полностью контролируется кодом самого inspector.