DocFxForUnity

<< Description | Usage | Contributing >>

Description

This package is designed to facilitate the integration of DocFx into Unity projects.

It is inspired by https://github.com/NormandErwan/DocFxForUnity.

Features

Integration of DocFx into Unity projects.
CI environment support, including GitHub Actions.
Generation method can be invoked from the command line interface (CLI).
- Generate sln/csproj files.
- Copy referenced assemblies for documentation generation.
Provides a custom DocFx template with the following features:
- UPM-like CSS.
- Collapsing and displaying inherited members at the bottom of the page.
- Collapsing and displaying inherited classes.

Usage

Setup for your Unity project

Install DocFX.

Clone this repository and copy Documentation/ folder to your Unity project.

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

Edit Documentation/docfx.json to config documentation.
See https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#3-docfxjson-format for more details.

{
  "metadata": [
    {
      ...
      "src": [
        {
          "src": "..", // relative path from Documentation/docfx.json. This is the root of your Unity project.
          "files": [
            "Your.CsProject.One.csproj", // Add your csproj files.
            "Your.CsProject.Two.csproj",
            "Glob.Is.Supported.*.csproj"
          ]
        }
      ]
    }
  ],
  "build": {
    "globalMetadata": {
      "_appTitle": "Example documentation", // Change this to your document title.
      "_appFooter": "Example documentation", // Change this to your document footer.
      ...
    },
    "sitemap": {
      "baseUrl": "https://mob-sakai.github.io/DocFxForUnity" // Change this to your GitHub Pages URL.
    }
    ...
  }
  ...

Edit Documentation/filterConfig.yml to filter namespaces/types/members/etc. to generate documentation.
See https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-by-uid for more details.

apiRules:
- exclude:
    uidRegex: ^YourNameSpace\.ToIgnore
    type: Namespace
- exclude:
    uidRegex: ^YourNameSpace\.(TypeToIgnore_One|TypeToIgnore_One)
    type: Type
- exclude:
    uidRegex: ^YourNameSpace\.YourType\.Member.*ToIgnore
    type: Member

Execute DocFx to generate documentation. The generated website will be visible at http://localhost:8080.
```
$ docfx Documentation/docfx.json --seve
```

Setup for GitHubActions

If you are using GitHub Actions, please refer to the build_documentation.yml workflow.

This workflow is responsible for generating and saving documentation that can be published as GitHub Pages.

To publish it as GitHub Pages, make sure to enable the "deploy" step.

Contributing

Issues

Issues are very valuable to this project.

Ideas are a valuable source of contributions others can make
Problems show where this project is lacking
With a question you show where contributors can improve the user experience

Pull Requests

Pull requests are, a great way to get your ideas into this repository.
See CONTRIBUTING.md.

Support

This is an open source project that I am developing in my spare time.
If you like it, please support me.
With your support, I can spend more time on development. :)