Home

Awesome

DocFX for Unity

DocFX usage example for Unity projects

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 a simple Unity example project which documentation is automatically generated and deployed online: https://normanderwan.github.io/DocFxForUnity/. It references both C# API and Unity API.

DocFxForUnity documentation manual
DocFxForUnity documentation manual
DocFxForUnity documentation scripting API
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. Document your classes and methods. See https://docs.microsoft.com/en-us/dotnet/csharp/codedoc for more details.

  6. (Optional) Add your manual pages:

    • Write a Markdown file for each page in Documentation/manual/.
    • Keep a list of these pages on Documentation/manual/toc.yml.

  7. (Optional) Add resources such as images:

  8. (Optional) Document your namespaces:

  9. 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. Next push on main 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

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.