From 9c437c2067e9e0142ad5799696388c2acb25f3d5 Mon Sep 17 00:00:00 2001
From: Jan Tattermusch <jtattermusch@google.com>
Date: Thu, 31 Aug 2017 11:23:03 +0200
Subject: [PATCH] Use docfx to generate C# API reference

---
 src/csharp/doc/.gitignore                  |  2 +
 src/csharp/doc/README.md                   |  9 ++-
 src/csharp/doc/docfx.json                  | 37 ++++++++++
 src/csharp/doc/grpc_csharp_public.shfbproj | 83 ----------------------
 src/csharp/doc/toc.yml                     |  3 +
 5 files changed, 50 insertions(+), 84 deletions(-)
 create mode 100644 src/csharp/doc/.gitignore
 create mode 100644 src/csharp/doc/docfx.json
 delete mode 100644 src/csharp/doc/grpc_csharp_public.shfbproj
 create mode 100644 src/csharp/doc/toc.yml

diff --git a/src/csharp/doc/.gitignore b/src/csharp/doc/.gitignore
new file mode 100644
index 00000000000..09ee235efcd
--- /dev/null
+++ b/src/csharp/doc/.gitignore
@@ -0,0 +1,2 @@
+html
+obj
diff --git a/src/csharp/doc/README.md b/src/csharp/doc/README.md
index 585500b5cab..46cce013a18 100644
--- a/src/csharp/doc/README.md
+++ b/src/csharp/doc/README.md
@@ -1,2 +1,9 @@
+DocFX-generated C# API Reference
+--------------------------------
 
-SandCastle project files to generate HTML reference documentation.
\ No newline at end of file
+Install docfx based on instructions here: https://github.com/dotnet/docfx
+
+```
+# generate docfx documentation into ./html directory
+$ docfx
+```
diff --git a/src/csharp/doc/docfx.json b/src/csharp/doc/docfx.json
new file mode 100644
index 00000000000..7219d0e7a69
--- /dev/null
+++ b/src/csharp/doc/docfx.json
@@ -0,0 +1,37 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": ["Grpc.Core/Grpc.Core.csproj",
+                    "Grpc.Auth/Grpc.Auth.csproj",
+                    "Grpc.Core.Testing/Grpc.Core.Testing.csproj",
+                    "Grpc.HealthCheck/Grpc.HealthCheck.csproj",
+                    "Grpc.Reflection/Grpc.HealthCheck.csproj"],
+          "exclude": [ "**/bin/**", "**/obj/**" ],
+          "cwd": ".."
+        }
+      ],
+      "properties": { "TargetFramework": "net45" },
+      "dest": "obj/api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [ "**/*.yml" ],
+        "cwd": "obj/api",
+        "dest": "api"
+      },
+      {
+        "files": [ "toc.yml"],
+      }
+    ],
+    "globalMetadata": {
+      "_appTitle": "gRPC C#",
+      "_enableSearch": true,
+      "_disableContribution": true
+    },
+    "dest": "html"
+  }
+}
diff --git a/src/csharp/doc/grpc_csharp_public.shfbproj b/src/csharp/doc/grpc_csharp_public.shfbproj
deleted file mode 100644
index fab953da353..00000000000
--- a/src/csharp/doc/grpc_csharp_public.shfbproj
+++ /dev/null
@@ -1,83 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-  <PropertyGroup>
-    <!-- The configuration and platform will be used to determine which assemblies to include from solution and
-				 project documentation sources -->
-    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
-    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
-    <SchemaVersion>2.0</SchemaVersion>
-    <ProjectGuid>{77e3da09-fc92-486f-a90a-99ca788e8b59}</ProjectGuid>
-    <SHFBSchemaVersion>2015.6.5.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 -->
-    <FrameworkVersion>.NET Framework 4.5</FrameworkVersion>
-    <OutputPath>..\..\..\doc\ref\csharp\html</OutputPath>
-    <Language>en-US</Language>
-    <DocumentationSources>
-      <DocumentationSource sourceFile="..\Grpc.Auth\Grpc.Auth.csproj" />
-<DocumentationSource sourceFile="..\Grpc.Core\Grpc.Core.csproj" />
-<DocumentationSource sourceFile="..\Grpc.HealthCheck\Grpc.HealthCheck.csproj" />
-<DocumentationSource sourceFile="..\Grpc.Reflection\Grpc.Reflection.csproj" />
-<DocumentationSource sourceFile="..\Grpc.Core.Testing\Grpc.Core.Testing.csproj" /></DocumentationSources>
-    <BuildAssemblerVerbosity>OnlyWarningsAndErrors</BuildAssemblerVerbosity>
-    <HelpFileFormat>Website</HelpFileFormat>
-    <IndentHtml>False</IndentHtml>
-    <KeepLogFile>True</KeepLogFile>
-    <DisableCodeBlockComponent>False</DisableCodeBlockComponent>
-    <CleanIntermediates>True</CleanIntermediates>
-    <HelpFileVersion>1.0.0.0</HelpFileVersion>
-    <MaximumGroupParts>2</MaximumGroupParts>
-    <NamespaceGrouping>False</NamespaceGrouping>
-    <SyntaxFilters>Standard</SyntaxFilters>
-    <SdkLinkTarget>Blank</SdkLinkTarget>
-    <RootNamespaceContainer>True</RootNamespaceContainer>
-    <PresentationStyle>VS2013</PresentationStyle>
-    <Preliminary>False</Preliminary>
-    <NamingMethod>MemberName</NamingMethod>
-    <HelpTitle>gRPC C#</HelpTitle>
-    <ContentPlacement>AboveNamespaces</ContentPlacement>
-    <HtmlHelpName>Documentation</HtmlHelpName>
-    <NamespaceSummaries>
-      <NamespaceSummaryItem name="Grpc.Auth" isDocumented="True">Provides OAuth2 based authentication for gRPC. &lt;c&gt;Grpc.Auth&lt;/c&gt; currently consists of a set of very lightweight wrappers and uses C# &lt;a href="https://www.nuget.org/packages/Google.Apis.Auth/"&gt;Google.Apis.Auth&lt;/a&gt; library.</NamespaceSummaryItem>
-      <NamespaceSummaryItem name="Grpc.Core" isDocumented="True">Main namespace for gRPC C# functionality. Contains concepts representing both client side and server side gRPC logic.
-
-&lt;seealso cref="Grpc.Core.Channel"/&gt; 
-&lt;seealso cref="Grpc.Core.Server"/&gt;</NamespaceSummaryItem>
-      <NamespaceSummaryItem name="Grpc.Core.Logging" isDocumented="True">Provides functionality to redirect gRPC logs to application-specified destination.</NamespaceSummaryItem>
-      <NamespaceSummaryItem name="Grpc.Core.Utils" isDocumented="True">Various utilities for gRPC C#.</NamespaceSummaryItem>
-    </NamespaceSummaries>
-    <MissingTags>Summary, Parameter, AutoDocumentCtors, Namespace, TypeParameter, AutoDocumentDispose</MissingTags>
-  </PropertyGroup>
-  <!-- There are no properties for these groups.  AnyCPU needs to appear in order for Visual Studio to perform
-			 the build.  The others are optional common platform types that may appear. -->
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x86' ">
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x64' ">
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x64' ">
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|Win32' ">
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|Win32' ">
-  </PropertyGroup>
-  <!-- Import the SHFB build targets -->
-  <Import Project="$(SHFBROOT)\SandcastleHelpFileBuilder.targets" />
-  <!-- The pre-build and post-build event properties must appear *after* the targets file import in order to be
-			 evaluated correctly. -->
-  <PropertyGroup>
-    <PreBuildEvent>
-    </PreBuildEvent>
-    <PostBuildEvent>
-    </PostBuildEvent>
-    <RunPostBuildEvent>OnBuildSuccess</RunPostBuildEvent>
-  </PropertyGroup>
-</Project>
\ No newline at end of file
diff --git a/src/csharp/doc/toc.yml b/src/csharp/doc/toc.yml
new file mode 100644
index 00000000000..c3a1e415ab1
--- /dev/null
+++ b/src/csharp/doc/toc.yml
@@ -0,0 +1,3 @@
+- name: API Documentation
+  href: obj/api/
+  homepage: obj/api/Grpc.Core.yml