CHANGE: docs tools update

.yamato/wrench/package-pack-jobs.yml

@@ -33,3 +33,28 @@ package_pack_-_inputsystem:
     Job Maintainers: '#rm-packageworks'
     Wrench: 3.2.1.0
 
+# Pack Package Manager DocTools
+package_pack_-_package-manager-doctools:
+  name: Package Pack - package-manager-doctools
+  agent:
+    image: package-ci/ubuntu-22.04:v4
+    type: Unity::VM::GPU
+    flavor: b1.large
+  commands:
+  - command: npm install upm-ci-utils@stable -g --registry https://artifactory.prd.cds.internal.unity3d.com/artifactory/api/npm/upm-npm
+    timeout: 20
+    retries: 10
+  - command: upm-ci package pack --package-path Packages/com.unity.package-manager-doctools
+  - command: cp upm-ci~/packages/packages.json upm-ci~/packages/com.unity.package-manager-doctools_packages.json
+  after:
+  - command: bash .yamato/generated-scripts/infrastructure-instability-detection-linux.sh
+  artifacts:
+    packages:
+      paths:
+      - upm-ci~/packages/**/*
+  variables:
+    UPMCI_ACK_LARGE_PACKAGE: 1
+  metadata:
+    Job Maintainers: '#rm-packageworks'
+    Wrench: 3.2.1.0
+

.yamato/wrench/wrench_config.json

@@ -38,6 +38,31 @@
         ]
       },
       "postPackCommands": []
+    },
+    "com.unity.package-manager-doctools": {
+      "directory": "Packages/com.unity.package-manager-doctools/",
+      "prePackCommands": [],
+      "preTestCommands": {
+        "MacOs13": [],
+        "MacOs13Arm": [],
+        "Ubuntu1804": [],
+        "Ubuntu2004": [],
+        "Ubuntu2204": [],
+        "Win10": [],
+        "Win10GPU": [],
+        "Win11": [],
+        "Win11Arm": [],
+        "Win11GPU": []
+      },
+      "InternalOnly": false,
+      "NeverPublish": false,
+      "MaxEditorVersion": "",
+      "coverageEnabled": false,
+      "coverageCommands": [
+        "generateAdditionalMetrics;generateHtmlReport;assemblyFilters:ASSEMBLY_NAME;"
+      ],
+      "dependantsToIgnoreInPreviewApv": {},
+      "postPackCommands": []
     }
   },
   "releasing_packages": [

Assets/Tests/InputSystem/DocumentationBasedAPIVerficationTests.cs

@@ -44,6 +44,56 @@
         Directory.CreateDirectory(docsPath);
         var inputSystemPackageInfo = UnityEditor.PackageManager.PackageInfo.FindForAssetPath("Packages/com.unity.inputsystem");
 
+        // PMDT 3.x generates API docs from .csproj files rather than compiled assemblies.
+        // When no IDE is configured (CI fresh clones), no .csproj files exist and PMDT
+        // generates no API documentation. Generate minimal .csproj files for InputSystem
+        // package assemblies using the CompilationPipeline API.
+        var projectName = new DirectoryInfo(Directory.GetCurrentDirectory()).Name;
+        if (!File.Exists($"{projectName}.sln"))
+        {
+            var assemblies = UnityEditor.Compilation.CompilationPipeline.GetAssemblies(
+                UnityEditor.Compilation.AssembliesType.Editor);
+            foreach (var asm in assemblies)
+            {
+                if (asm.sourceFiles.Length == 0 ||
+                    !asm.sourceFiles.Any(f => f.Replace("\\", "/").Contains("Packages/com.unity.inputsystem/")))
+                    continue;
+                var csprojPath = $"{asm.name}.csproj";
+                if (File.Exists(csprojPath))
+                    continue;
+                var csprojContent = new StringBuilder();
+                csprojContent.AppendLine("<?xml version=\"1.0\" encoding=\"utf-8\"?>");
+                csprojContent.AppendLine("<Project ToolsVersion=\"4.0\" DefaultTargets=\"Build\" " +
+                    "xmlns=\"http://schemas.microsoft.com/developer/msbuild/2003\">");
+                // DefineConstants must be in an unconditional PropertyGroup so DocFX reads them
+                // regardless of whether MSBuild's Platform property is set.
+                csprojContent.AppendLine("  <PropertyGroup>");
+                csprojContent.AppendLine($"    <DefineConstants>{string.Join(";", asm.defines)}</DefineConstants>");
+                csprojContent.AppendLine("  </PropertyGroup>");
+                csprojContent.AppendLine("  <PropertyGroup Condition=\" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' \">");
+                csprojContent.AppendLine($"    <AssemblyName>{asm.name}</AssemblyName>");
+                csprojContent.AppendLine("    <TargetFrameworkVersion>v4.7.1</TargetFrameworkVersion>");
+                csprojContent.AppendLine("    <OutputType>Library</OutputType>");
+                csprojContent.AppendLine("    <AllowUnsafeBlocks>True</AllowUnsafeBlocks>");
+                csprojContent.AppendLine("    <LangVersion>9.0</LangVersion>");
+                csprojContent.AppendLine("    <NoConfig>true</NoConfig>");
+                csprojContent.AppendLine("    <NoStdLib>true</NoStdLib>");
+                csprojContent.AppendLine("  </PropertyGroup>");
+                csprojContent.AppendLine("  <ItemGroup>");
+                foreach (var src in asm.sourceFiles)
+                    csprojContent.AppendLine($"    <Compile Include=\"{src}\" />");
+                csprojContent.AppendLine("  </ItemGroup>");
+                csprojContent.AppendLine("  <ItemGroup>");
+                foreach (var refPath in asm.compiledAssemblyReferences)
+                    csprojContent.AppendLine(
+                        $"    <Reference Include=\"{Path.GetFileNameWithoutExtension(refPath)}\">" +
+                        $"<HintPath>{refPath}</HintPath></Reference>");
+                csprojContent.AppendLine("  </ItemGroup>");
+                csprojContent.AppendLine("</Project>");
+                File.WriteAllText(csprojPath, csprojContent.ToString(), Encoding.UTF8);
+            }
+        }
+
 #if HAVE_DOCTOOLS_INSTALLED
         (_documentationBuilderLogs, _docsFolder) = Documentation.Instance.GenerateEx(inputSystemPackageInfo, InputSystem.version.ToString(), docsPath);
         _docsFolder = Path.Combine(docsPath, _docsFolder);
@@ -394,6 +444,14 @@
             if (link.StartsWith("https://"))
                 continue;
 
+            // javascript: URIs are used by the PMDT 3.x HTML theme for collapsible navigation elements
+            if (link.StartsWith("javascript:"))
+                continue;
+
+            // xref: URIs are unresolved DocFX cross-references to types outside this package
+            if (link.StartsWith("xref:"))
+                continue;
+
             if (link == "#top")
                 continue;
 

Packages/com.unity.inputsystem/Documentation~/built-in-interactions.md

@@ -93,7 +93,7 @@ A [`SlowTapInteraction`](xref:UnityEngine.InputSystem.Interactions.SlowTapIntera
 
 ## MultiTap
 
-You can use `MultiTap` to detect double-click or multi-click gestures. For a [`MultiTapInteraction`](xref:UnityEngine.InputSystem.Interactions.MultiTapInteraction) to trigger, the user must press a control and release it within [`tapTime`](xref:UnityEngine.InputSystem.Interactions.MultiTapInteraction) seconds, repeating the press-and-release process [`tapCount`](xref:UnityEngine.InputSystem.Interactions.MultiTapInteraction) times. There can't be more than [`tapDelay`](xref:UnityEngine.InputSystem.Interactions.MultiTapInteraction) seconds between taps. 
+You can use `MultiTap` to detect double-click or multi-click gestures. For a [`MultiTapInteraction`](xref:UnityEngine.InputSystem.Interactions.MultiTapInteraction) to trigger, the user must press a control and release it within [`tapTime`](xref:UnityEngine.InputSystem.Interactions.MultiTapInteraction) seconds, repeating the press-and-release process [`tapCount`](xref:UnityEngine.InputSystem.Interactions.MultiTapInteraction) times. There can't be more than [`tapDelay`](xref:UnityEngine.InputSystem.Interactions.MultiTapInteraction) seconds between taps.
 
 |__Parameters__|Type|Default value|
 |---|---|---|

Packages/com.unity.inputsystem/Documentation~/projectMetadata.json

@@ -1,7 +1,8 @@
 {
     "hideGlobalNamespace": true,
+    "DefineConstants": "UNITY_INPUT_SYSTEM_PROJECT_WIDE_ACTIONS;PACKAGE_DOCS_GENERATION",
     "xref": [
         "com.unity.xr.openxr",
         "com.unity.xr.interaction.toolkit"
     ]
-}
+}

Packages/com.unity.inputsystem/InputSystem/Runtime/InputSystem.cs

@@ -2904,8 +2904,8 @@ public static event Action onSettingsChange
         /// <example>
         /// <code>
         /// InputSystem.customBindingPathValidators += (string bindingPath) => {
-        ///     // Mark <Gamepad> bindings with a warning
-        ///     if (!bindingPath.StartsWith("<Gamepad>"))
+        ///     // Mark &lt;Gamepad&gt; bindings with a warning
+        ///     if (!bindingPath.StartsWith("&lt;Gamepad&gt;"))
         ///         return null;
         ///
         ///     // Draw the warning information in the Binding Properties panel

Tools/CI/Recipes/EditorFunctionalTests.cs

@@ -24,10 +24,9 @@ protected override IJobBuilder ProduceJob(string jobName, Package package, Platf
             .WithDescription(jobName)
             .WithPlatform(platform);
 
-        if (platform.System == SystemType.Windows)
-        {
-            job.WithCommands(c => c.Add(InputSystemSettings.NetfxInstallCmd));
-        }
+        job.WithCommands(c => c.Add(platform.System == SystemType.Windows
+            ? InputSystemSettings.DocfxInstallCmdWindows
+            : InputSystemSettings.DocfxInstallCmdUnix));
 
         job.WithCommands(c => c
                 .Add(InputSystemSettings.DoctoolsInstallCmd)

Tools/CI/Recipes/EditorPerformanceTests.cs

@@ -24,10 +24,9 @@ protected override IJobBuilder ProduceJob(string jobName, Package package, Platf
             .WithDescription(jobName)
             .WithPlatform(platform);
 
-        if (platform.System == SystemType.Windows)
-        {
-            job.WithCommands(c => c.Add(InputSystemSettings.NetfxInstallCmd));
-        }
+        job.WithCommands(c => c.Add(platform.System == SystemType.Windows
+            ? InputSystemSettings.DocfxInstallCmdWindows
+            : InputSystemSettings.DocfxInstallCmdUnix));
 
         job.WithCommands(c => c
                 .Add(InputSystemSettings.DoctoolsInstallCmd)

Tools/CI/Recipes/StandaloneFunctionalTests.cs

@@ -23,10 +23,9 @@ protected override IJobBuilder ProduceJob(string jobName, Package package, Platf
             .WithDescription(jobName)
             .WithPlatform(platform);
 
-        if (platform.System == SystemType.Windows)
-        {
-            job.WithCommands(c => c.Add(InputSystemSettings.NetfxInstallCmd));
-        }
+        job.WithCommands(c => c.Add(platform.System == SystemType.Windows
+            ? InputSystemSettings.DocfxInstallCmdWindows
+            : InputSystemSettings.DocfxInstallCmdUnix));
 
         job.WithCommands(c => c
                 .Add(InputSystemSettings.DoctoolsInstallCmd)

Tools/CI/Recipes/StandaloneIl2CppFunctionalTests.cs

@@ -23,10 +23,9 @@ protected override IJobBuilder ProduceJob(string jobName, Package package, Platf
             .WithDescription(jobName)
             .WithPlatform(platform);
 
-        if (platform.System == SystemType.Windows)
-        {
-            job.WithCommands(c => c.Add(InputSystemSettings.NetfxInstallCmd));
-        }
+        job.WithCommands(c => c.Add(platform.System == SystemType.Windows
+            ? InputSystemSettings.DocfxInstallCmdWindows
+            : InputSystemSettings.DocfxInstallCmdUnix));
 
         job.WithCommands(c => c
                 .Add(InputSystemSettings.DoctoolsInstallCmd)

Tools/CI/Recipes/StandaloneIl2CppPerformanceTests.cs

@@ -23,10 +23,9 @@ protected override IJobBuilder ProduceJob(string jobName, Package package, Platf
             .WithDescription(jobName)
             .WithPlatform(platform);
 
-        if (platform.System == SystemType.Windows)
-        {
-            job.WithCommands(c => c.Add(InputSystemSettings.NetfxInstallCmd));
-        }
+        job.WithCommands(c => c.Add(platform.System == SystemType.Windows
+            ? InputSystemSettings.DocfxInstallCmdWindows
+            : InputSystemSettings.DocfxInstallCmdUnix));
 
         job.WithCommands(c => c
                 .Add(InputSystemSettings.DoctoolsInstallCmd)

Tools/CI/Recipes/StandalonePerformanceTests.cs

@@ -23,10 +23,9 @@ protected override IJobBuilder ProduceJob(string jobName, Package package, Platf
             .WithDescription(jobName)
             .WithPlatform(platform);
 
-        if (platform.System == SystemType.Windows)
-        {
-            job.WithCommands(c => c.Add(InputSystemSettings.NetfxInstallCmd));
-        }
+        job.WithCommands(c => c.Add(platform.System == SystemType.Windows
+            ? InputSystemSettings.DocfxInstallCmdWindows
+            : InputSystemSettings.DocfxInstallCmdUnix));
 
         job.WithCommands(c => c
                 .Add(InputSystemSettings.DoctoolsInstallCmd)

Tools/CI/Settings/InputSystemSettings.cs

@@ -21,9 +21,20 @@ public class InputSystemSettings : AnnotatedSettingsBase
     public static readonly string BranchName = "develop";
     public static readonly string InputSystemPackageName = "com.unity.inputsystem";
 
-    // Command to install .NET Framework 4.7.1 Developer Pack which is used by doctools on Windows.
-    public static readonly string NetfxInstallCmd = "%GSUDO% choco install netfx-4.7.1-devpack -y --ignore-detected-reboot --ignore-package-codes";
-    public static readonly string DoctoolsInstallCmd = "git clone --branch \"2.3.0-preview\" git@github.cds.internal.unity3d.com:unity/com.unity.package-manager-doctools.git Packages/com.unity.package-manager-doctools";
+    // NOTE: Starting with PMDT 3.0.0, DocFX is no longer bundled with the package and must be
+    // installed separately as a dotnet tool. See:
+    // https://docs.unity3d.com/Packages/com.unity.package-manager-doctools@3.14/manual/installation.html
+    //
+    // dotnet SDK availability: confirmed present on package-ci images (Windows, Mac, and Ubuntu) via
+    // #devs-pets / #devs-ci Slack history - it's a centrally maintained, version-pinned component of
+    // the image family. So extra .NET SDK install step is needed here.
+    public static readonly string DocfxVersion = "2.70.0";
+
+    // Installs the DocFX version PMDT 3.x expects, as a dotnet tool, per-platform.
+    public static readonly string DocfxInstallCmdWindows = $"dotnet tool install docfx --version {DocfxVersion} --tool-path %USERPROFILE%/.pmdt";
+    public static readonly string DocfxInstallCmdUnix = $"dotnet tool install docfx --version {DocfxVersion} --tool-path $HOME/.pmdt";
+
+    public static readonly string DoctoolsInstallCmd = "git clone --branch \"3.14.8-preview\" git@github.cds.internal.unity3d.com:unity/com.unity.package-manager-doctools.git Packages/com.unity.package-manager-doctools";
 
     public WrenchPackage InputSystemPackage => Wrench.Packages[InputSystemPackageName];