Update SHFB in order to build documentation without MSBuild (#3083)

Author: hazzik

.gitignore

@@ -19,3 +19,7 @@ TestResult.xml
 .vs/
 /build-common/NHibernate.dev.props
 /doc/reference/master.xml
+/doc/bin/
+/doc/obj/
+/Tools/bin/
+/Tools/obj/

Tools/actual_msbuild.cmd

@@ -11,7 +11,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="vswhere" Version="2.1.4" />
     <PackageReference Include="NUnit.Console" Version="3.10.0" />
   </ItemGroup>
 

Tools/packages.csproj

@@ -1,4 +1,5 @@
-<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="3.5">
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="14.0">
+  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
   <PropertyGroup>
     <!-- The configuration and platform will be used to determine which
          assemblies to include from solution and project documentation
@@ -7,26 +8,27 @@
     <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
     <SchemaVersion>2.0</SchemaVersion>
     <ProjectGuid>{91f431cd-23fb-4ed4-a690-0344073c65f0}</ProjectGuid>
-    <SHFBSchemaVersion>1.8.0.0</SHFBSchemaVersion>
+    <SHFBSchemaVersion>2017.9.26.0</SHFBSchemaVersion>
     <!-- AssemblyName, Name, and RootNamespace are not used by SHFB but Visual
          Studio adds them anyway -->
     <AssemblyName>Documentation</AssemblyName>
     <RootNamespace>Documentation</RootNamespace>
     <Name>Documentation</Name>
     <!-- SHFB properties -->
-    <OutputPath>${doc.out.dir}</OutputPath>
+    <FrameworkVersion>.NET Framework 4.6.1</FrameworkVersion>
+    <OutputPath></OutputPath>
     <HtmlHelpName>NHibernateAPI</HtmlHelpName>
-    <HelpFileFormat>HtmlHelp1x</HelpFileFormat>
+    <HelpFileFormat>HtmlHelp1</HelpFileFormat>
     <CopyrightText>NHibernate</CopyrightText>
     <CopyrightHref>https://nhibernate.info</CopyrightHref>
     <FeedbackEMailAddress>https://groups.google.com/group/nhibernate-development</FeedbackEMailAddress>
     <FeedbackEMailLinkText>nhibernate team</FeedbackEMailLinkText>
     <HelpTitle>NHibernate API Reference</HelpTitle>
     <IndentHtml>False</IndentHtml>
-    <HelpFileVersion>${project.version}</HelpFileVersion>
+    <HelpFileVersion>1.0.0.0</HelpFileVersion>
     <DocumentationSources>
-      <DocumentationSource sourceFile="${root.dir}/src/NHibernate/bin/${build.config}/net461/NHibernate.dll" />
-      <DocumentationSource sourceFile="${root.dir}/src/NHibernate/bin/${build.config}/net461/Nhibernate.xml" />
+      <DocumentationSource sourceFile="../src/NHibernate/bin/$(Configuration)/net461/NHibernate.dll" />
+      <DocumentationSource sourceFile="../src/NHibernate/bin/$(Configuration)/net461/Nhibernate.xml" />
     </DocumentationSources>
   </PropertyGroup>
   <!-- There are no properties for these two groups but they need to appear in
@@ -35,6 +37,10 @@
   </PropertyGroup>
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
   </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="EWSoftware.SHFB.NETFramework" Version="4.8.0.2" />
+  </ItemGroup>
+  <Import Project="$(MSBuildToolsPath)\Microsoft.Common.targets" Condition="'$(MSBuildRestoreSessionId)' != ''" />
   <!-- Import the SHFB build targets -->
-  <Import Project="$(SHFBROOT)\SandcastleHelpFileBuilder.targets" />
+  <Import Project="$(SHFBROOT)\SandcastleHelpFileBuilder.targets" Condition="'$(MSBuildRestoreSessionId)' == ''" />
 </Project>

doc/.gitignore

@@ -42,15 +42,7 @@
 		</zip>
 	</target>
 
-	<target name="apidocbuilder-project" depends="init">
-		<copy file="NHibernate.shfbproj.template" tofile="NHibernate.shfbproj" overwrite="true">
-			<filterchain>
-				<expandproperties />
-			</filterchain>
-		</copy>
-	</target>
-
-	<target name="api" depends="init apidocbuilder-project" description="Generates the API documentation (in MSDN style if available)">
+	<target name="api" depends="init" description="Generates the API documentation (in MSDN style if available)">
 		<uptodate property="api.uptodate">
 			<sourcefiles>
 				<include name="${root.dir}/src/NHibernate/bin/${build.config}/net461/*.dll" />
@@ -65,8 +57,12 @@
 		<echo if="${api.uptodate}">API documentation is up to date, skipping generation step.</echo>
 
 		<if test="${not api.uptodate}">
-			<exec program="${path::combine(tools.dir, 'actual_msbuild.cmd')}">
-				<arg line="NHibernate.shfbproj" />
+			<exec program="dotnet">
+				<arg value="build" />
+				<arg value="/p:HelpFileVersion=&quot;${project.version}&quot;" />
+				<arg value="/p:OutputPath=&quot;${doc.out.dir}&quot;" />
+				<arg value="/p:Configuration=&quot;${build.config}&quot;" />
+				<arg value="NHibernate.shfbproj" />
 			</exec>
 		</if>
 	</target>

doc/NHibernate.shfbproj.template renamed to doc/NHibernate.shfbproj

@@ -22,8 +22,8 @@ the documentation. You don't need to download and install Saxon, its jars are
 present in the repository.
 
 You need HTML Help Workshop to build the CHM help file, and Sandcastle Help File
-Builder (SHFB - https://github.com/EWSoftware/SHFB) to build the HtmlHelp2 help
-file.
+Builder v2021.11.7.0 or later (SHFB - https://github.com/EWSoftware/SHFB) to
+build the HtmlHelp2 help file.
 
 ================================================================================
 DocBook Quick Start