KorStrix/DocFxForUnity

DocFX usage example for Unity projects (Unity API xref map included).

DocFX for Unity

DocFX usage example for Unity projects (Unity API xref map included)

DocFX tool generates a clean documentation that looks like the Unity documentation with a manual (written in Markdown) and a scripting API (from the C# scripts of the project).

This repository contains:

1. A simple Unity project which documentation is automatically generated and deployed online: https://normanderwan.github.io/DocFxForUnity/.
2. Every reference to the C# API and the Unity API (the so-called xref maps). They are be automatically linked on the documentation.

DocFxForUnity documentation manual

DocFxForUnity documentation scripting API

Setup your documentation

1. Install DocFX.

2. Copy the Documentation/ folder to your Unity project:

     .
     ├── Assets
   + ├── Documentation
     ├── Package
     ├── ProjectSettings
     └── README.md

3. Edit the following properties in Documentation/docfx.json, keep the others as it is:

     {
       "build": {
         "globalMetadata": // Edit your documentation website info, see: https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#322-reserved-metadata
         {
           "_appTitle": "Example Unity documentation",
           "_appFooter": "Example Unity documentation",
           "_enableSearch": true
         },
         "sitemap":
         {
           "baseUrl": "https://normanderwan.github.io/DocFxForUnity" // The URL of your documentation website
         }
     }

   It's the configuration file of your documentation. See https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#3-docfxjson-format for more details.

4. Edit Documentation/filterConfig.yml:

   apiRules:
   - include: # The namespaces to generate
       uidRegex: ^Your\.Namespace1
       type: Namespace
   - include:
       uidRegex: ^Your\.Namespace2
       type: Namespace
   - exclude:
       uidRegex: .* # Every other namespaces are ignored
       type: Namespace

   It tells DocFX which namespaces you want to generate the documentation. See https://dotnet.github.io/docfx/tutorial/howto_filter_out_unwanted_apis_attributes.html for more details.

5. Write your manual pages in Markdown in Documentation/manual/. You must keep a list of these pages on Documentation/manual/toc.yml.

6. Add resources such as images to Documentation/resources/.

7. Generate your documentation:

   • On a command line opened on your project, run:

     cp README.md Documentation/index.md
     docfx Documentation/docfx.json --serve

   • The generated website will be visible at http://localhost:8080.

If you want to have a more similar look to the Unity documentation, see this UnityFX template for DocFX: https://github.com/code-beans/UnityFX.

Generate automatically your documentation

If you're using GitHub:

1. Copy the .github/workflows/documentation.yml workflow to your Unity project:

     .
   + ├── .github
   + |   └── workflows
   + |       └── documentation.yml
     ├── Assets
     ├── Documentation
     ├── Package
     ├── ProjectSettings
     └── README.md

2. Generate a new personal access token with repo scope.

3. Copy this token on your repository secrets with name AccessToken.

4. Next push on master branch will build and deploy your documentation to https://<USERNAME>.github.io/<REPOSITORY>/!

If you're using GitLab, use the provided .gitlab-ci.yml. Generated website is pushed to a public/ directory. See the GitLab Pages documentation for more details.

Troubleshooting / FAQ

• DocFX outputs: Warning:[ExtractMetadata]No project detected for extracting metadata.

  Solution: On Unity, click Asset > Open C# Project to generate the required .csproj.

• DocFX outputs: Warning:[ExtractMetadata]No metadata is generated for Assembly-CSharp,Assembly-CSharp-Editor.

  Solution: Make sure your included your namespace in Documentation/filterConfig.yml:

  - include:
    uidRegex: ^Your\.Namespace1
    type: Namespace

• If you want to reference a specific version of Unity, change this line on your docfx.json:

  "xref": [ "https://normanderwan.github.io/DocFxForUnity/Unity/<version>/xrefmap.yml" ],
  

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

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.