mrtk_developmentreleases/2.0.0releases/2.1.0releases/2.2.0
  • 指南
  • API 文档
  • 指南
  • Contributing
  • How to use DocFX

    Show / Hide Table of Contents
    • MRTK入门
      • 发布说明
      • MRTK包内容
      • 从早期版本更新
      • 从HTK更新
      • 生成和部署MRTK
      • NuGet包
      • MRTK配置对话框
      • 开始使用 MRTK和XR SDK
      • 性能
      • 全息图稳定
      • 在大型项目中使用MRTK
    • 架构
      • 概述
      • 框架和运行时
      • 输入系统
        • 术语
        • 核心系统
        • Controllers, pointers, and focus
      • 系统,扩展服务和 data providers
    • 功能概述
      • 边界系统 Boundary System
        • 边界系统概述
        • 配置边界可视化
      • 相机系统 Camera System
        • 相机系统概述
        • Camera Settings Providers
          • Windows 混合现实相机设置
          • Unity AR相机设置[实验性]
          • 创建camera settings provider
      • 跨平台支持
        • 为iOS和Android配置MRTK
      • 检测平台能力
      • 诊断系统 Diagnostics System
        • 诊断系统概述
        • 配置诊断系统
        • 使用可视化分析器
      • 扩展服务 Extension Services
        • 扩展服务创建向导
        • 场景过渡服务概述
      • 输入系统 Input System
        • 输入概览
        • 输入动作 Input Actions
        • 输入事件 Input Events
        • Input Providers
          • Input Providers 概述
          • 创建一个 input data provider
        • 控制器 Controllers
        • 眼动跟踪 Eyes
          • 概述
          • 入门
          • 通过代码访问数据
          • 验证跟踪校准 Validate Tracking Calibration
        • 凝视 Gaze
        • 手势 Gestures
        • 手部 Hands
        • 如何添加近距离交互 Near Interaction
        • 编辑器内输入模拟 In-Editor Input Simulation
        • 指针 Pointers
        • 语音输入 Voice Input
          • 语音转录 Dictation
          • 语音(命令和控制) Speech
      • 多场景系统 Multi Scene System
        • 多场景系统概述
        • 场景类型 Scene Types
        • 内容场景加载 Content Scene Loading
        • 监测内容加载 Monitoring Content Loading
        • 光照场景操作 Lighting Scene Operations
      • 打包 Packaging
        • MRTK包 MRTK Packages
        • MRTK模块化 MRTK Modularization
      • 配置文件 Profiles
        • 配置文件概述
        • 配置指南 Configuration Guide
      • 渲染 Rendering
        • 材质实例概述 Material Instance Overview
        • Shaders
          • MRTK标准着色器 MRTK Standard Shader
      • 服务 Services
        • 什么是混合现实特性
        • 什么是 MixedRealityServiceRegistry 和IMixedRealityServiceRegistrar
        • 扩展服务 Extension services
      • 空间感知系统 Spatial Awareness System
        • 空间感知概述
        • Spatial Observers
          • 为设备配置 Observers
          • 为Editor配置 Observers
          • 通过代码控制 Observers
          • 创建自定义 Observer
      • 传送系统概述 Teleport System Overview
      • 工具
        • Dependency Window
        • Extension Service Creation Wizard
        • Holographic Remoting
        • Input Animation Recording
          • Input Animation File Format Specification
        • Optimize Window
        • Runtime tools
          • Controller Mapping tool
      • UX 构建模块
        • 工具箱窗口 Toolbox Window
        • 按钮 Button
        • 边界框 Bounding Box
        • 对象操纵器 Object Manipulator
        • Manipulation Handler [废弃]
        • Slate
        • 系统键盘 System Keyboard
        • 可交互的 Interactable
        • Solvers
          • 点击放置 Tap to Place
        • 对象集合 Object Collection
        • 提示工具条 Tooltips
        • 滑动条 Slider
        • 手部菜单 Hand Menu
        • 近处菜单 Near Menu
        • 应用程序栏 App Bar
        • 指尖可视化 Fingertip Visualization
        • 进度指示器 Progress Indicator
        • 对话框 Dialog [实验性]
        • 手势教学 Hand Coach [实验性]
        • 可滚动对象集合 Scrolling Object Collection [实验性]
        • 脉冲着色器 Pulse Shader [实验性]
        • 停靠控件 Dock Control [实验性]
        • HoloLens键盘助手 [实验性]
      • 示例场景
        • 示例中心
        • 手势交互示例场景
        • 眼动跟踪示例场景
    • Contributing
      • Contributing Overview
      • Coding Guidelines
      • Writing and Running Tests
      • Writing Documentation
      • Pull Requests
      • Experimental Features
      • Breaking Changes
      • How to use DocFX
    • Planning
      • Roadmap
    • Notice
    • Authors

    Developer portal generation guide

    MRTK uses docfx to generate html documentation out of triple slash comments in code and .md files in the MRTK repository. Docfx documentation generation is automatically triggered by CI on completed PRs in the mrtk_development branch. The current state of the developer documentation can be found on the MRTK github.io page

    Docfx supports DFM Docfx Flavored Markdown which includes GFM Github Flavored Markdown. The full documentation and feature list can be found here

    Docfx is not only converting but also checking all used local links in the documentation. If a path can't be resolved it won't be converted into its html equivalent. Therefor it's important to only use relative paths when referring to other local files.

    Building docfx locally

    The docfx build files in the MRTK repo can be used to create a local version of the developer documentation in a doc/ subfolder in the root of the project.

    Setup

    • get the latest version of docfx
    • extract the files in a folder on your computer
    • add the folder to your PATH in your environment variables

    Generation

    • open a powershell or cmd prompt in the root of the MRTK project
    • execute docfx docfx.json (optionally with the -f option to force a rebuild of doc files)
    • execute docfx serve doc (optionally with -p portnumber if you don't want to use the 8888 default port)
    • open a web browser with localhost:portnumber

    Note that on executing the docfx command on the json build file docfx will show any broken links in the documentation as warning. Please make sure whenever you perform changes on any of the documentation files or API to update all links pointing to these articles or code.

    Verifying docfx on github

    Whenever a PR includes a change that might affect documentation CI has to be executed to run a check on docfx for broken links. This can be triggered by posting the command /azp run mrtk_docs into the PR if the user has sufficient rights to do so. The command will trigger a CI job which will add a docs build to the checks section of the PR.

    Using crefs and hrefs in /// documented code

    Docfx supports crefs in /// documented code. It will translate those references to links pointing to the generated api documentation or to external documentation websites. External xref services for resolving links to external libraries/apis can be added to the docfx.json build settings file in the property xrefService.

    For external apis that don't provide an xref service hrefs to the documentation website can be added to the comments.

    Examples:

    /// Links to MRTK internal class SystemType
    /// <see cref="Microsoft.MixedReality.Toolkit.Utilities.SystemType"/>
    
    /// Links to external API - link provided by xref service
    /// <see cref="System.Collections.Generic.ICollection{Type}.Contains"/>
    
    /// Links to Unity web API reference
    /// <see href="https://docs.unity3d.com/ScriptReference/EditorGUI.PropertyField.html">EditorGUI.PropertyField</see>
    

    Linking in .md documentation files

    Docfx is translating and validating all relative local links on generation, there's no special syntax required. Referring to another documentation article should always be done by referring to the corresponding .md file, never the auto generated .html file. Please note that all links to local files need to be relative to the file you're modifying.

    Linking to the API documentation can be done by using cross references. Docfx automatically generated UIDs for all API docs by mangling the signature.

    Example:

    This links to the BoundarySystem API as well as this short version: Microsoft.MixedReality.Toolkit.Boundary

    This links to the [BoundarySystem API](xref:Microsoft.MixedReality.Toolkit.Boundary)
    as well as this short version: @Microsoft.MixedReality.Toolkit.Boundary
    

    Enumerating available xrefs

    Xref syntax can be difficult to remember - it's possible to enumerate all of the available xref IDs by first running docfx locally:

    docfx docfx.json

    This will generate an xrefmap.yml file, which will be located in docs/xrefmap.yml.

    For example, in order to link the following overload of HandleEvent, the syntax is fairly arcane:

    - uid: Microsoft.MixedReality.Toolkit.BaseEventSystem.HandleEvent``1(BaseEventData,ExecuteEvents.EventFunction{``0})
      name: HandleEvent<T>(BaseEventData, ExecuteEvents.EventFunction<T>)
      href: api/Microsoft.MixedReality.Toolkit.BaseEventSystem.html#Microsoft_MixedReality_Toolkit_BaseEventSystem_HandleEvent__1_BaseEventData_ExecuteEvents_EventFunction___0__
      commentId: M:Microsoft.MixedReality.Toolkit.BaseEventSystem.HandleEvent``1(BaseEventData,ExecuteEvents.EventFunction{``0})
      name.vb: HandleEvent(Of T)(BaseEventData, ExecuteEvents.EventFunction(Of T))
      fullName: Microsoft.MixedReality.Toolkit.BaseEventSystem.HandleEvent<T>(BaseEventData, ExecuteEvents.EventFunction<T>)
      fullName.vb: Microsoft.MixedReality.Toolkit.BaseEventSystem.HandleEvent(Of T)(BaseEventData, ExecuteEvents.EventFunction(Of T))
      nameWithType: BaseEventSystem.HandleEvent<T>(BaseEventData, ExecuteEvents.EventFunction<T>)
      nameWithType.vb: BaseEventSystem.HandleEvent(Of T)(BaseEventData, ExecuteEvents.EventFunction(Of T))
    

    It's easy, however, to search for the name and then use the entire uid field as the xref.

    In this example, the xref would look like: (xref:Microsoft.MixedReality.Toolkit.BaseEventSystem.HandleEvent1(BaseEventData,ExecuteEvents.EventFunction{0}))

    Adding new .md files to developer docs

    Docfx will pick up any .md files in folders that are added as content files in the build section of the docfx.json and generate html files out of them. For new folders a corresponding entry in the build file needs to be added.

    Navigation entries

    To determine the entries of the navigation in the developer docs docfx uses toc.yml/toc.md - table of content files. The toc file in the root of the project defines entries in the top navigation bar whereas the toc.yml files in the subfolders of the repo define subtopics in the sidebar navigation. toc.yml files can be used for structuring and there can be any amount of those files. For more info about defining entries for toc.yml check the docfx documentation entry on toc.

    Resource files

    There are some files like images, videos or PDFs that the documentation can refer to but are not converted by docfx. For those files there's a resource section in the docfx.json. Files in that section will only be copied over without performing any conversion on them.

    Currently there's a definition for the following resource types:

    ResourceType Path
    Images Documentation/Images/

    Releasing a new version

    Multiple versions of developer docs are supported and can be switched by the version drop down in the top menu bar. If you're releasing a new version perform the following steps to have your version on the developer docs page.

    1. Optional: Adjusting your docfx.json
      Depending on whether you want to have the "Improve this doc" to point to a specific version of the github repo you will have to add the following entry to the globalMetaData section in the docfx.json file before calling the docfx command:

      "_gitContribute": {
          "repo": "https://github.com/Microsoft/MixedRealityToolkit-Unity.git",
          "branch": "mrtk_development"
      }
      

      If you don't set this up docfx will default to the branch and repo of the current folder you're calling docfx from.

    2. Create your docfx docs by calling docfx docfx.json in the root of the repo

    3. Create a folder with the name of your version in the version folder of the gh-pages branch and copy the contents of the generated doc folder into that folder

    4. Add your version number into the versionArray in web/version.js

    5. Push the modified version.js to mrtk_development branch and the changes in gh-pages branch

    CI will pick up the changes done to the version.js file and update the version dropdown automatically.

    Supporting development branches on CI

    The versioning system can also be used for showing doc versions from other dev branches that are built by CI. When setting up CI for one of those branches make sure your powershell script on CI copies the contents of the generated docfx output into a version folder named after your branch and add the corresponding version entry into the web/version.js file.

    Good practices for developers

    • Use relative paths whenever referring to MRTK internal pages
    • Use cross references for linking to any MRTK API page by using the mangled UID
    • Use crefs and hrefs to link to internal or external documentation in /// comments
    • Use the indicated folders in this doc for resource files
    • Run docfx locally and check for warnings in the output whenever you modify existing APIs or update documentation pages
    • Watch out for docfx warnings on CI after completing and merging your PR into one of the official MRTK branches

    Common errors when generating docs

    • toc.yml errors: usually happens when an .md file gets moved/renamed or removed but the table of content file (toc.yml) pointing to that file wasn't updated accordingly. On the website this will result in a broken link on our top level or side navigation
    • /// comments errors
      • xml tag errors - docfx like any other xml parser can't handle malformed xml tags.
      • typos in crefs
      • incomplete namespace identifiers - docfx won't need the full namespace to the symbol you're referring to but the relative part of the namespace that's not included in the surrounding namespace of the cref.
        • Example: if you're in a namespace Microsoft.MixedReality.Toolkit.Core.Providers.UnityInput and the file you want to link in is Microsoft.MixedReality.Toolkit.Core.Interfaces.IMixedRealityServiceRegistrar your cref can look like this: cref="Interfaces.IMixedRealityServiceRegistrar"
      • External crefs - As long as there's no xref service available (and listed in the docfx build file) crefs to external libraries won't work. If you still want to link to a specific external symbol that doesn't have xref service but an online api documentation you can use a href instead. Example: linking to EditorPrefs of Unity: <see href="https://docs.unity3d.com/ScriptReference/EditorPrefs.html">EditorPrefs</see>

    See also

    • MRTK documentation guide
    • MRTK developer documentation on github.io
    • DocFX
    • Improve this Doc
    In This Article
    • Building docfx locally
      • Setup
      • Generation
    • Verifying docfx on github
    • Using crefs and hrefs in /// documented code
    • Linking in .md documentation files
    • Enumerating available xrefs
    • Adding new .md files to developer docs
      • Navigation entries
    • Resource files
    • Releasing a new version
      • Supporting development branches on CI
    • Good practices for developers
    • Common errors when generating docs
    • See also
    Back to top Generated by DocFX