Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 41 additions & 5 deletions .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,40 +17,76 @@ permissions:
jobs:
# Build the documentation
build:
name: build (docfx ${{ matrix.docfx }}, Unity ${{ matrix.unity }})
runs-on: ubuntu-latest # DocFX v2+ is cross-platform; no longer requires Windows
strategy:
fail-fast: false
matrix:
# Every tested DocFX version on the reference Unity version,
# then the latest DocFX on every other supported Unity version.
# The `renovate:` comments tell renovate.json which values to update.
include:
- { docfx: 2.60.0, unity: 6000.3.26f1 } # renovate: unity-lts
- { docfx: 2.64.0, unity: 6000.3.26f1 } # renovate: unity-lts
- { docfx: 2.77.0, unity: 6000.3.26f1 } # renovate: unity-lts
- { docfx: 2.81.0, unity: 6000.3.26f1, deploy: true } # renovate: docfx unity-lts
- { docfx: 2.81.0, unity: 6000.6.6f1 } # renovate: docfx unity-supported
steps:
- name: Checkout
uses: actions/checkout@v7
# with:
# submodules: true

# DocFX 2.60 cannot load the project with the .NET 8 SDK alone (NuGet.Frameworks load failure)
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: |
6.0.x
8.0.x

- name: Install DocFX
run: dotnet tool install -g docfx --version 2.77.0
run: dotnet tool install -g docfx --version ${{ matrix.docfx }}

- name: Cache Unity managed DLLs
id: cache-unity-dlls
uses: actions/cache@v6
with:
path: lib/UnityEngine
key: unity-managed-dlls-6000.0.73f1-v1
key: unity-managed-dlls-${{ matrix.unity }}-v1

- name: Extract Unity managed DLLs from game-ci image
if: steps.cache-unity-dlls.outputs.cache-hit != 'true'
run: |
mkdir -p lib
docker create --name unity-editor unityci/editor:ubuntu-6000.0.73f1-linux-il2cpp-3.2.2
docker create --name unity-editor unityci/editor:ubuntu-${{ matrix.unity }}-linux-il2cpp-3.2.2
docker cp unity-editor:/opt/unity/Editor/Data/Managed/UnityEngine lib/
docker rm unity-editor

- name: Use the Unity xref map of the tested version
run: |
unity='${{ matrix.unity }}'
sed -i "s#UnityXrefMaps/[0-9.]*/#UnityXrefMaps/${unity%.*}/#" Documentation/docfx.json

- name: Use README.md as index.md
run: cp README.md Documentation/index.md

- name: Build
run: docfx Documentation/docfx.json
run: docfx Documentation/docfx.json --warningsAsErrors

# A build can succeed without resolving Unity types: check the generated links
- name: Check Unity API links
run: |
unity='${{ matrix.unity }}'
page=_site/api/DocFxForUnity.Player.html
for type in Object Component Behaviour MonoBehaviour AudioClip; do
grep -q "href=\"https://docs.unity3d.com/${unity%.*}/Documentation/ScriptReference/$type.html\"" $page \
|| { echo "::error::Missing link to Unity $type in $page"; exit 1; }
done

# Upload the generated documentation (only on main for deployment)
- name: Upload site artifact
if: github.ref == 'refs/heads/main'
if: matrix.deploy && github.ref == 'refs/heads/main'
uses: actions/upload-pages-artifact@v5
with:
path: _site # Must equal the 'build.dest' value in docfx.json
Expand Down
14 changes: 10 additions & 4 deletions .gitlab-ci.yml
Original file line number Diff line number Diff line change
@@ -1,12 +1,18 @@
image: mcr.microsoft.com/dotnet/sdk:8.0
# The game-ci editor image ships the Unity managed DLLs that DocFX needs to resolve
# Unity types. Unity is never activated: only its files are read.
image: unityci/editor:ubuntu-6000.3.26f1-linux-il2cpp-3.2.2 # renovate: unity-lts

pages:
stage: deploy
variables:
UNITY_MANAGED_PATH: /opt/unity/Editor/Data/Managed/UnityEngine
DOTNET_ROOT: /opt/dotnet
script:
- dotnet tool install -g docfx --version 2.77.0
- export PATH="$HOME/.dotnet/tools:$PATH"
- curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 8.0 --install-dir "$DOTNET_ROOT"
- export PATH="$DOTNET_ROOT:$HOME/.dotnet/tools:$PATH"
- dotnet tool install -g docfx --version 2.81.0 # renovate: docfx
- cp README.md Documentation/index.md
- docfx Documentation/docfx.json
- docfx Documentation/docfx.json --warningsAsErrors
- mv _site public
artifacts:
paths:
Expand Down
2 changes: 1 addition & 1 deletion Documentation/DocFxForUnity.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@

<!-- Warning if no Unity DLLs found at all -->
<Warning Condition="'@(_UnityDll)' == ''"
Text="Unity managed DLLs not found. Set UNITY_MANAGED_PATH to your Unity installation's Managed/UnityEngine directory (e.g. /Applications/Unity/Hub/Editor/6000.0.73f1/Unity.app/Contents/Managed/UnityEngine), or install Unity Hub at its default location." />
Text="Unity managed DLLs not found. Set UNITY_MANAGED_PATH to your Unity installation's Managed/UnityEngine directory (e.g. /Applications/Unity/Hub/Editor/6000.3.26f1/Unity.app/Contents/Managed/UnityEngine), or install Unity Hub at its default location." />

<!-- Add assembly references for all discovered DLLs -->
<ItemGroup>
Expand Down
2 changes: 1 addition & 1 deletion Documentation/docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
}
},
"xref": [
"https://normanderwan.github.io/UnityXrefMaps/6000.0/xrefmap.yml",
"https://normanderwan.github.io/UnityXrefMaps/6000.3/xrefmap.yml",
"https://learn.microsoft.com/en-us/dotnet/.xrefmap.json"
],
"dest": "../_site"
Expand Down
2 changes: 1 addition & 1 deletion ProjectSettings/ProjectVersion.txt
Original file line number Diff line number Diff line change
@@ -1 +1 @@
m_EditorVersion: 6000.0.73f1
m_EditorVersion: 6000.3.26f1
89 changes: 68 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,32 @@ online: <https://normanderwan.github.io/DocFxForUnity/>. It references both C# A
|:----------------------------------:|
| [![DocFxForUnity documentation scripting API](https://normanderwan.github.io/DocFxForUnity/resources/ExampleScriptingApi.png)](https://normanderwan.github.io/DocFxForUnity/api/DocFxForUnity.Player.html) |

## Compatibility

Every combination below is built by the [CI workflow](https://github.com/NormandErwan/DocFxForUnity/blob/main/.github/workflows/documentation.yml) on each change.

| DocFX | Unity 6000.3 (6.3 LTS) | Unity 6000.6 (6.6) |
|-------|:----------------------:|:------------------:|
| 2.60.0 (unsupported, see below) | ✓ | |
| 2.64.0 | ✓ | |
| 2.77.0 | ✓ | |
| 2.81.0 <!-- renovate: docfx --> | ✓ | ✓ |

- Use DocFX **2.64 or later**, with the **.NET SDK 8.0 or later**.
- Since DocFX 2.62, a C# compilation error stops the build. DocFX must therefore find the Unity managed DLLs,
see [Troubleshooting](#troubleshooting--faq). DocFX 2.60 and 2.61 build without them with only warnings, and emit pages with
no link to the Unity API.
- Unity 6000.3 is the version of this example project. The CI also builds against Unity 6000.6 with its own xref
map, see [Reference another Unity version](#reference-another-unity-version).

## Setup your documentation

1. [Install DocFX](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool).
1. Install the [.NET SDK](https://dotnet.microsoft.com/download) 8.0 or later, then [DocFX](https://dotnet.github.io/docfx/index.html):

```bash
dotnet tool update -g docfx
```

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

```diff
Expand All @@ -38,7 +61,7 @@ online: <https://normanderwan.github.io/DocFxForUnity/>. It references both C# A
```javascript
{
"build": {
"globalMetadata": // Edit your documentation website info, see: https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#322-reserved-metadata
"globalMetadata": // Edit your documentation website info, see: https://dotnet.github.io/docfx/reference/docfx-json-reference.html#predefined-metadata
{
"_appTitle": "Example Unity documentation",
"_appFooter": "Example Unity documentation",
Expand All @@ -52,7 +75,7 @@ online: <https://normanderwan.github.io/DocFxForUnity/>. It references both C# A
```

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.
See <https://dotnet.github.io/docfx/reference/docfx-json-reference.html> for more details.

4. Edit `Documentation/filterConfig.yml`:

Expand All @@ -70,9 +93,9 @@ online: <https://normanderwan.github.io/DocFxForUnity/>. It references both C# A
```

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.
See <https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis> for more details.

5. Document your classes and methods. See <https://docs.microsoft.com/en-us/dotnet/csharp/codedoc> for more details.
5. Document your classes and methods. See <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/> for more details.

6. (Optional) Add your manual pages:
- Write a Markdown file for each page in `Documentation/manual/`.
Expand All @@ -81,7 +104,7 @@ online: <https://normanderwan.github.io/DocFxForUnity/>. It references both C# A
7. (Optional) Add resources such as images:
- Copy them to `Documentation/resources/`.
- Reference them on your docs or manual pages.
- See <https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html#link-to-a-file-using-relative-path> for more details.
- See <https://dotnet.github.io/docfx/docs/links-and-cross-references.html> for more details.

8. (Optional) Document your namespaces:
- For each namespace, add a `Assets/Scripts/Your/Namespace1/Your.Namespace1.md` file:
Expand All @@ -107,6 +130,21 @@ online: <https://normanderwan.github.io/DocFxForUnity/>. It references both C# A
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>.

### Unity package layout

A [Unity package](https://docs.unity3d.com/Manual/cus-layout.html) has no `Assets/` folder. To document one:

1. Copy the folder as `Documentation~/` at the package root: Unity ignores folders whose name ends with `~`.
2. In `Documentation~/DocFxForUnity.csproj`, point the sources to your package scripts:

```xml
<Compile Include="../Runtime/**/*.cs" />
```

3. In `Documentation~/docfx.json`, point the namespace pages under `build.overwrite[0].files` to the same folder:
`"Runtime/**/*.md"`.
4. Use `Documentation~/` instead of `Documentation/` in the commands and CI files.

## Generate automatically your documentation

If you're using GitHub:
Expand All @@ -125,14 +163,20 @@ If you're using GitHub:
└── README.md
```

The workflow builds every DocFX and Unity version of the [Compatibility](#compatibility) table. For your project,
keep a single entry in `jobs.build.strategy.matrix.include`, with `deploy: true` and your Unity version.
The `Check Unity API links` step reads `_site/api/DocFxForUnity.Player.html`: point it to one of your pages, or delete it.

2. [Configure the Pages of your repository to use GitHub Actions.](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)
3. Commit and push on the `main` branch: your documentation will be built and deployed to `https://<username>.github.io/<repository>`.

The workflow reads the Unity managed DLLs from the public [game-ci](https://game.ci/) editor Docker image
`unityci/editor:ubuntu-<unity version>-linux-il2cpp-3.2.2`. Unity is never activated, so no license is needed.

If you're using GitLab, use the provided
[`.gitlab-ci.yml`](https://github.com/NormandErwan/DocFxForUnity/blob/main/.gitlab-ci.yml).
Generated website is pushed to a `public/` directory. See the
[GitLab Pages documentation](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_four.html) for more
details.
[`.gitlab-ci.yml`](https://github.com/NormandErwan/DocFxForUnity/blob/main/.gitlab-ci.yml). It runs in the same
game-ci image. Set its `image` to your Unity version. Generated website is pushed to a `public/` directory. See the
[GitLab Pages documentation](https://docs.gitlab.com/user/project/pages/) for more details.

## Troubleshooting / FAQ

Expand All @@ -150,7 +194,7 @@ details.
type: Namespace
```

- MSBuild outputs: `Unity managed DLLs not found.`
- DocFX outputs `error CS0246: The type or namespace name 'UnityEngine' could not be found`, or MSBuild outputs `Unity managed DLLs not found.`

This means DocFX could not locate Unity's managed DLLs. It looks in three places, in order:
1. The `UNITY_MANAGED_PATH` environment variable (see below).
Expand All @@ -159,13 +203,16 @@ details.

If Unity Hub is installed at a non-default location, or you want to target a specific Unity version, set `UNITY_MANAGED_PATH` (see *Advanced: `UNITY_MANAGED_PATH`* below).

- If you want to reference a specific version of Unity, change this line on your `docfx.json`:
### Reference another Unity version

```json
"xref": [ "https://normanderwan.github.io/UnityXrefMaps/<version>/xrefmap.yml" ],
```
The links to the Unity API come from the xref map of [UnityXrefMaps](https://github.com/NormandErwan/UnityXrefMaps).
To link to the documentation of your Unity version, change this line on your `docfx.json`:

```json
"xref": [ "https://normanderwan.github.io/UnityXrefMaps/<version>/xrefmap.yml" ],
```

where `<version>` is a Unity version in the form of `YYYY.x` (*e.g.* 2022.3, 2023.2, 6000.0).
where `<version>` is a Unity version in the form of `YYYY.x` (*e.g.* 2022.3, 6000.3, 6000.6).

## Advanced: `UNITY_MANAGED_PATH`

Expand All @@ -179,21 +226,21 @@ Point it to the `UnityEngine` subfolder inside your Unity installation's `Manage

| OS | Example path |
|----|-------------|
| Windows | `C:\Program Files\Unity\Hub\Editor\6000.0.73f1\Editor\Data\Managed\UnityEngine` |
| macOS | `/Applications/Unity/Hub/Editor/6000.0.73f1/Unity.app/Contents/Managed/UnityEngine` |
| Linux | `~/Unity/Hub/Editor/6000.0.73f1/Editor/Data/Managed/UnityEngine` |
| Windows | `C:\Program Files\Unity\Hub\Editor\6000.3.26f1\Editor\Data\Managed\UnityEngine` |
| macOS | `/Applications/Unity/Hub/Editor/6000.3.26f1/Unity.app/Contents/Managed/UnityEngine` |
| Linux | `~/Unity/Hub/Editor/6000.3.26f1/Editor/Data/Managed/UnityEngine` |

Set it in your shell before running DocFX:

```bash
# macOS / Linux
export UNITY_MANAGED_PATH="/Applications/Unity/Hub/Editor/6000.0.73f1/Unity.app/Contents/Managed/UnityEngine"
export UNITY_MANAGED_PATH="/Applications/Unity/Hub/Editor/6000.3.26f1/Unity.app/Contents/Managed/UnityEngine"
docfx Documentation/docfx.json --serve
```

```powershell
# Windows (PowerShell)
$env:UNITY_MANAGED_PATH = "C:\Program Files\Unity\Hub\Editor\6000.0.73f1\Editor\Data\Managed\UnityEngine"
$env:UNITY_MANAGED_PATH = "C:\Program Files\Unity\Hub\Editor\6000.3.26f1\Editor\Data\Managed\UnityEngine"
docfx Documentation/docfx.json --serve
```

Expand Down
60 changes: 60 additions & 0 deletions renovate.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,65 @@
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": [
"config:recommended"
],
"customManagers": [
{
"customType": "regex",
"description": "Unity LTS version in CI files, on lines marked `# renovate: ... unity-lts`",
"managerFilePatterns": ["/^\\.github/workflows/documentation\\.yml$/", "/^\\.gitlab-ci\\.yml$/"],
"matchStrings": ["(?<currentValue>\\d+\\.\\d+\\.\\d+f\\d+)[^\\n]*# renovate:[^\\n]*\\bunity-lts\\b"],
"depNameTemplate": "Unity Editor",
"datasourceTemplate": "unity3d"
},
{
"customType": "regex",
"description": "Unity Update (SUPPORTED stream) version in CI files, on lines marked `# renovate: ... unity-supported`",
"managerFilePatterns": ["/^\\.github/workflows/documentation\\.yml$/"],
"matchStrings": ["(?<currentValue>\\d+\\.\\d+\\.\\d+f\\d+)[^\\n]*# renovate:[^\\n]*\\bunity-supported\\b"],
"depNameTemplate": "Unity Editor (Update)",
"datasourceTemplate": "unity3d",
"registryUrlTemplate": "https://services.api.unity.com/unity/editor/release/v1/releases?stream=SUPPORTED"
},
{
"customType": "regex",
"description": "Unity xref map of the reference Unity version",
"managerFilePatterns": ["/^Documentation/docfx\\.json$/"],
"matchStrings": ["UnityXrefMaps/(?<currentValue>\\d+\\.\\d+)/xrefmap\\.yml"],
"depNameTemplate": "Unity Editor",
"datasourceTemplate": "unity3d",
"versioningTemplate": "loose",
"extractVersionTemplate": "^(?<version>\\d+\\.\\d+)\\."
},
{
"customType": "regex",
"description": "Latest DocFX, on lines marked `# renovate: docfx`; the older tested versions stay pinned",
"managerFilePatterns": ["/^\\.github/workflows/documentation\\.yml$/", "/^\\.gitlab-ci\\.yml$/", "/^README\\.md$/"],
"matchStrings": [
"docfx: (?<currentValue>\\d+\\.\\d+\\.\\d+)[^\\n]*# renovate:[^\\n]*\\bdocfx\\b",
"docfx --version (?<currentValue>\\d+\\.\\d+\\.\\d+) # renovate: docfx",
"\\| (?<currentValue>\\d+\\.\\d+\\.\\d+) <!-- renovate: docfx -->"
],
"depNameTemplate": "docfx",
"datasourceTemplate": "nuget",
"versioningTemplate": "semver"
}
],
"packageRules": [
{
"description": "Update Unity version, game-ci image and xref map together",
"matchDepNames": ["Unity Editor"],
"groupName": "Unity LTS"
},
{
"description": "SUPPORTED stream releases are not flagged stable by the unity3d datasource",
"matchDepNames": ["Unity Editor (Update)"],
"groupName": "Unity Update",
"ignoreUnstable": false
},
{
"description": "Update every latest-DocFX occurrence together",
"matchDepNames": ["docfx"],
"groupName": "DocFX"
}
]
}
Loading