fix(csproj): auto-detect Unity Hub DLLs on Windows/macOS/Linux

DocFxForUnity.csproj

@@ -1,20 +1,48 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <TargetFramework>netstandard2.1</TargetFramework>
-    <!--
-      In CI: Unity managed DLLs are extracted to lib/UnityEngine/ by the workflow.
-      Locally: set the UNITY_MANAGED_PATH environment variable to your Unity installation:
-        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
-    -->
-    <UnityManagedPath Condition="'$(UNITY_MANAGED_PATH)' != ''">$(UNITY_MANAGED_PATH)</UnityManagedPath>
-    <UnityManagedPath Condition="'$(UnityManagedPath)' == ''">lib/UnityEngine</UnityManagedPath>
   </PropertyGroup>
 
   <Target Name="AddUnityReferences" BeforeTargets="ResolveAssemblyReferences">
-    <ItemGroup>
+    <!--
+      Priority 1: UNITY_MANAGED_PATH environment variable (explicit override).
+      Priority 2: lib/UnityEngine/ extracted by CI from the game-ci Docker image.
+      Priority 3: auto-detect from default Unity Hub installation paths (glob over installed versions).
+      If nothing is found, a MSBuild warning is emitted.
+    -->
+
+    <!-- Priorities 1 & 2: explicit path -->
+    <PropertyGroup>
+      <UnityManagedPath Condition="'$(UNITY_MANAGED_PATH)' != ''">$(UNITY_MANAGED_PATH)</UnityManagedPath>
+      <UnityManagedPath Condition="'$(UnityManagedPath)' == '' and Exists('$(MSBuildProjectDirectory)/lib/UnityEngine')">$(MSBuildProjectDirectory)/lib/UnityEngine</UnityManagedPath>
+    </PropertyGroup>
+
+    <!-- Collect DLLs from explicit path (priorities 1 or 2) -->
+    <ItemGroup Condition="'$(UnityManagedPath)' != ''">
       <_UnityDll Include="$(UnityManagedPath)/*.dll" />
+    </ItemGroup>
+
+    <!-- Priority 3: auto-detect on Windows -->
+    <ItemGroup Condition="'$(UnityManagedPath)' == '' and $([MSBuild]::IsOSPlatform('Windows'))">
+      <_UnityDll Include="C:\Program Files\Unity\Hub\Editor\*\Editor\Data\Managed\UnityEngine\*.dll" />
+    </ItemGroup>
+
+    <!-- Priority 3: auto-detect on macOS -->
+    <ItemGroup Condition="'$(UnityManagedPath)' == '' and $([MSBuild]::IsOSPlatform('OSX'))">
+      <_UnityDll Include="/Applications/Unity/Hub/Editor/*/Unity.app/Contents/Managed/UnityEngine/*.dll" />
+    </ItemGroup>
+
+    <!-- Priority 3: auto-detect on Linux -->
+    <ItemGroup Condition="'$(UnityManagedPath)' == '' and $([MSBuild]::IsOSPlatform('Linux'))">
+      <_UnityDll Include="$(HOME)/Unity/Hub/Editor/*/Editor/Data/Managed/UnityEngine/*.dll" />
+    </ItemGroup>
+
+    <!-- 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." />
+
+    <!-- Add assembly references for all discovered DLLs -->
+    <ItemGroup>
       <Reference Include="%(_UnityDll.Filename)">
         <HintPath>%(_UnityDll.FullPath)</HintPath>
         <Private>false</Private>

README.md

@@ -20,17 +20,20 @@ online: <https://normanderwan.github.io/DocFxForUnity/>. It references both C# A
 ## Setup your documentation
 
 1. [Install DocFX](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool).
-2. Copy the `Documentation/` folder to your Unity project:
+2. Copy the `Documentation/` folder and `DocFxForUnity.csproj` to your Unity project:
 
     ```diff
       .
       ├── Assets
+    + ├── DocFxForUnity.csproj
     + ├── Documentation
       ├── Package
       ├── ProjectSettings
       └── README.md
     ```
 
+    You can rename `DocFxForUnity.csproj` to match your project — just update the filename in `Documentation/docfx.json` under `metadata[0].src[0].files` accordingly.
+
 3. Edit the following properties in `Documentation/docfx.json`, keep the others as it is:
 
     ```javascript
@@ -136,25 +139,64 @@ details.
 
 - DocFX outputs: `Warning:[ExtractMetadata]No project detected for extracting metadata.`
 
-    Solution: On Unity, click [Asset > Open C# Project](https://docs.microsoft.com/fr-fr/visualstudio/cross-platform/media/vstu_open-csharp-project.png?view=vs-2019) to generate the required `.csproj`.
+    Solution: Make sure you copied `DocFxForUnity.csproj` (or your renamed version) to the root of your Unity project, and that the filename matches the entry in `Documentation/docfx.json` under `metadata[0].src[0].files`.
 
 - DocFX outputs: `Warning:[ExtractMetadata]No metadata is generated for Assembly-CSharp,Assembly-CSharp-Editor.`
 
-    Solution: Make sure your included your namespace in `Documentation/filterConfig.yml`:
+    Solution: Make sure you included your namespace in `Documentation/filterConfig.yml`:
 
     ```yaml
     - include:
       uidRegex: ^Your\.Namespace1
       type: Namespace
     ```
 
+- 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).
+    2. `lib/UnityEngine/` at the project root (populated automatically by the CI workflow).
+    3. The default Unity Hub installation directory for your OS.
+
+    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`:
 
   ```json
   "xref": [ "https://normanderwan.github.io/UnityXrefMaps/<version>/xrefmap.yml" ],
   ```
 
-  where `<version>` is a Unity version in the form of `YYYY.x` (*e.g.* 2017.4, 2018.4, 2019.3).
+  where `<version>` is a Unity version in the form of `YYYY.x` (*e.g.* 2022.3, 2023.2, 6000.0).
+
+## Advanced: `UNITY_MANAGED_PATH`
+
+By default, `DocFxForUnity.csproj` auto-detects the Unity managed DLLs from the standard Unity Hub installation directory. Set `UNITY_MANAGED_PATH` when you need to:
+
+- Use a Unity version installed at a non-default location.
+- Pin to a specific version when multiple Unity versions are installed.
+- Work without Unity Hub (standalone Unity install).
+
+Point it to the `UnityEngine` subfolder inside your Unity installation's `Managed` directory:
+
+| 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` |
+
+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"
+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"
+docfx Documentation/docfx.json --serve
+```
 
 ## Disclaimer