Unity API references for DocFX

Automatically add clickable links to the Unity API on a DocFX documentation

Generates references of the Unity API to use with DocFX (the cross reference maps). DocFX will set clickable all the references of the Unity API on your documentation.

Basic usage

1. Make sure you have setup a DocFX documentation. You can follow the DocFxForUnity instructions otherwise.

2. Add this line to your docfx.json:

   • If you want to reference the latest stable version of Unity:

     "build": {
         "xref": [
     +        "https://normanderwan.github.io/UnityXrefMaps/xrefmap.yml"
         ],
     }

   • If you want to reference a specific version of Unity:

     "build": {
         "xref": [
     +        "https://normanderwan.github.io/UnityXrefMaps/<version>/xrefmap.yml"
         ],
     }

     where <version> is a Unity version in the form of YYYY.x (e.g. 2018.4, 2019.3, 2020.1).

   • If you prefer relying in a offline file:

     "build": {
         "xref": [
     +        "UnityXrefMap.yml"
         ],
     }

     where UnityXrefMap.yml has been downloaded from one of the link above and placed next to your docfx.json.

3. Generate your documentation!

Advanced usage

Install tool with: dotnet tool install --global UnityXrefMaps.

Generate documentation for a specific version of the Unity editor

You need to provide at least:

• A docfx.json file. You can base it on the docfx.json in the repository.
• The version of the Unity editor.
• Trim UnityEngine and UnityEditor because Unity omits these namespaces in its documentation links.

Example:

unityxrefmaps \
    --repositoryPath xref/Unity/Repository \
    --repositoryTags 6000.0.1f1 \
    --trimNamespaces UnityEditor \
    --trimNamespaces UnityEngine

Generate documentation for a specific version of a Unity package

You need to provide at least:

• A docfx.json file. You can base it on the docfx.json in the repository.
• The package version.
• The API URL, which will be different for each package.

Example:

unityxrefmaps \
    --repositoryUrl "https://github.com/needle-mirror/com.unity.inputsystem.git" \
    --repositoryTags '1.0.0' \
    --apiUrl "https://docs.unity3d.com/Packages/com.unity.inputsystem@{0}/api/"

Testing that links are generated correctly

Providing an xrefmap.yml file will check each href element to see if it is a valid URL.

Example:

unityXrefMaps test \
    --xrefPath xrefmap.yml

Contribute

• To run this program:

  1. Install .NET 9.0 SDK.

  2. Install DocFX.

  3. Clone this repository on your computer.

  4. Open a terminal on the cloned repository and run:

     cd UnityXrefMaps
     dotnet run

• For any question or comment, please open a new issue.

• If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome!

Disclaimer

This repository is not sponsored by or affiliated with Unity Technologies or its affiliates. “Unity” is a trademark or registered trademark of Unity Technologies or its affiliates in the U.S. and elsewhere.