diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index 81ffbc2..bb6c2c2 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -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
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 544356d..d1c96f0 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -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:
diff --git a/Documentation/DocFxForUnity.csproj b/Documentation/DocFxForUnity.csproj
index 64c367b..7191005 100644
--- a/Documentation/DocFxForUnity.csproj
+++ b/Documentation/DocFxForUnity.csproj
@@ -44,7 +44,7 @@
+ 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." />
diff --git a/Documentation/docfx.json b/Documentation/docfx.json
index d557030..56cb05b 100644
--- a/Documentation/docfx.json
+++ b/Documentation/docfx.json
@@ -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"
diff --git a/ProjectSettings/ProjectVersion.txt b/ProjectSettings/ProjectVersion.txt
index c0912af..e6134cb 100644
--- a/ProjectSettings/ProjectVersion.txt
+++ b/ProjectSettings/ProjectVersion.txt
@@ -1 +1 @@
-m_EditorVersion: 6000.0.73f1
+m_EditorVersion: 6000.3.26f1
diff --git a/README.md b/README.md
index 2bf28ec..50128a5 100644
--- a/README.md
+++ b/README.md
@@ -17,9 +17,32 @@ online: . It references both C# A
|:----------------------------------:|
| [](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 | ✓ | ✓ |
+
+- 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
@@ -38,7 +61,7 @@ online: . 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",
@@ -52,7 +75,7 @@ online: . It references both C# A
```
It's the configuration file of your documentation.
- See for more details.
+ See for more details.
4. Edit `Documentation/filterConfig.yml`:
@@ -70,9 +93,9 @@ online: . It references both C# A
```
It tells DocFX which namespaces you want to generate the documentation.
- See for more details.
+ See for more details.
-5. Document your classes and methods. See for more details.
+5. Document your classes and methods. See for more details.
6. (Optional) Add your manual pages:
- Write a Markdown file for each page in `Documentation/manual/`.
@@ -81,7 +104,7 @@ online: . 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 for more details.
+ - See for more details.
8. (Optional) Document your namespaces:
- For each namespace, add a `Assets/Scripts/Your/Namespace1/Your.Namespace1.md` file:
@@ -107,6 +130,21 @@ online: . It references both C# A
If you want to have a more similar look to the Unity documentation, see this UnityFX template for DocFX:
.
+### 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
+
+ ```
+
+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:
@@ -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://.github.io/`.
+The workflow reads the Unity managed DLLs from the public [game-ci](https://game.ci/) editor Docker image
+`unityci/editor:ubuntu--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
@@ -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).
@@ -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//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//xrefmap.yml" ],
+```
- where `` is a Unity version in the form of `YYYY.x` (*e.g.* 2022.3, 2023.2, 6000.0).
+where `` is a Unity version in the form of `YYYY.x` (*e.g.* 2022.3, 6000.3, 6000.6).
## Advanced: `UNITY_MANAGED_PATH`
@@ -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
```
diff --git a/renovate.json b/renovate.json
index 5db72dd..695245b 100644
--- a/renovate.json
+++ b/renovate.json
@@ -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": ["(?\\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": ["(?\\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/(?\\d+\\.\\d+)/xrefmap\\.yml"],
+ "depNameTemplate": "Unity Editor",
+ "datasourceTemplate": "unity3d",
+ "versioningTemplate": "loose",
+ "extractVersionTemplate": "^(?\\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: (?\\d+\\.\\d+\\.\\d+)[^\\n]*# renovate:[^\\n]*\\bdocfx\\b",
+ "docfx --version (?\\d+\\.\\d+\\.\\d+) # renovate: docfx",
+ "\\| (?\\d+\\.\\d+\\.\\d+) "
+ ],
+ "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"
+ }
]
}