Doc Fx For Unity by NormandErwan - 6

Games & Projects

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

Unity 2017.4.26f1BSD 3-Clause "New" or "Revised" LicenseUpdated 65 days agoCreated on September 26th, 2017
Go to source

DocFX for Unity

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

Build status Example documentation website

Build status Unity API xref maps

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 project as example. Its documentation is automatically generated and deployed online with every git push: https://normanderwan.github.io/DocFxForUnity/.

Every reference to the C# API or to the Unity API will be automatically linked.

DocFxForUnity documentation manual DocFxForUnity documentation scripting API
DocFxForUnity documentation manual DocFxForUnity documentation scripting API

Setup your documentation

  • Copy the Documentation/ folder to your Unity project (at the same level than the Assets/ folder).
  • Edit Documentation/docfx.json:
  {
    "metadata": [
      ...
    ],
    "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
      }
    }
  }
  • Edit Documentation/filterConfig.yml:
apiRules:
// The namespaces to generate
- include:
    uidRegex: ^Your\.Namespace
    type: Namespace
// Every other namespaces are ignored
- exclude:
    uidRegex: .*
    type: Namespace
  • Write manual pages in Markdown on Documentation/manual/.You must keep a list of these pages on Documentation/manual/toc.yml.
  • Add resources such as images to Documentation/resources/

Generate your documentation

  • Install DocFX.
  • 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.

Generate automatically your documentation

It requires some steps but the setup is quick!

  • Setup GitHub Pages:

    • Setup GitHub Pages to use the gh-branch of your repository. The documentation will be generated as a static website that will be pushed on this branch.
  • Setup AppVeyor:

  • Setup appveyor.yml build instructions:

    • Copy the appveyor.yml from this repository to the root of your Unity project.
    • As AppVeyor will push on the gh-pages branch, it need an authentication token (you don’t want to copy/paste your password!):
    • Edit all the environment variables on your appveyor.yml:
    environment:
      git_repo: <github_user_name/github_repo_name>
      git_user_email: <github_user_email>
      git_user_name: <github_user_name>
      auth_token:
        secure: <your_secure_token> # The secure, encrypted token!
    
    • Push appveyor.yml it to GitHub.
  • Try a build on your Appveyor project!

You can also found a .gitlab-ci.yml if you’re using GitLab instead of GitHub. Generated website is pushed to a public/ directory. See the GitLab Pages documentation for more details.

Show all projects by NormandErwan