docs: Add a package table to README.md

.kokoro/autogenerate.sh

@@ -81,6 +81,11 @@ done
 git add --all
 git commit -a -m "chore: Delete obsolete Discovery docs" || true
 
+# Regenerate the package table in README.md
+dotnet run --project Src/Tools/UpdateReadmePackageList -- README.md DiscoveryJson
+git add --all
+git commit -a -m "chore: Update the package table in README.md" || true
+
 # Push changes to git, not to the main branch but to branchname
 # We change the origin URL so that we can push with SSH
 git remote set-url origin [email protected]:googleapis/google-api-dotnet-client.git

Src/Tools/BuildGeneratedArgumentTranslator/BuildGeneratedArgumentTranslator.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
@@ -7,8 +7,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
-    <PackageReference Include="Google.Apis.Discovery.v1" Version="1.68.0" />
+    <ProjectReference Include="..\ToolUtilities\ToolUtilities.csproj" />
   </ItemGroup>
 
 </Project>

Src/Tools/BuildGeneratedArgumentTranslator/Program.cs

@@ -18,15 +18,7 @@
 // for details of the expected arguments. The first argument is the generation directory,
 // and is specified by BuildGenerated.sh itself.
 
-// This code copies elements from the REST generator. While duplication isn't great,
-// this is code that isn't expected to change regularly, and it's cleaner to make this
-// small utility standalone than to put it into the generator itself (or have some common
-// dependency library).
-
-using Google.Api.Generator.Rest.Models;
-using Google.Api.Generator.Utils;
-using Google.Apis.Discovery.v1.Data;
-using Google.Apis.Json;
+using ToolUtilities;
 
 if (args.Length == 0)
 {
@@ -57,15 +49,8 @@
         continue;
     }
 
-    // The code below is taken from PackageModel in the REST generator.
-    var discoveryDoc = NewtonsoftJsonSerializer.Instance.Deserialize<RestDescription>(File.ReadAllText(path));
-
-    var className = (discoveryDoc.CanonicalName ?? discoveryDoc.Name).Replace(" ", "").ToMemberName();
-    string versionNoDots = discoveryDoc.Version.Replace('.', '_');
-    var camelizedPackagePath = discoveryDoc.PackagePath is null
-        ? ""
-        : string.Join('.', discoveryDoc.PackagePath.Split('/').Select(part => part.ToUpperCamelCase())) + ".";
-    var packageName = $"Google.Apis.{camelizedPackagePath}{className}.{versionNoDots}";
+    var json = File.ReadAllText(path);
+    string packageName = Discovery.GetPackageName(json);
     Console.Write($" {generationDir}/{packageName}");
 }
 

Src/Tools/ToolUtilities/Discovery.cs

@@ -0,0 +1,49 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using Google.Api.Generator.Rest.Models;
+using Google.Api.Generator.Utils;
+using Google.Apis.Discovery.v1.Data;
+using Google.Apis.Json;
+
+namespace ToolUtilities;
+
+/// <summary>
+/// Utilities for working with Discovery docs.
+/// </summary>
+public static class Discovery
+{
+    public static RestDescription ParseDiscoveryJson(string discoveryJson) =>
+        NewtonsoftJsonSerializer.Instance.Deserialize<RestDescription>(discoveryJson);
+
+    /// <summary>
+    /// Returns the name of the package generated from the given Discovery doc (in JSON form).
+    /// </summary>
+    public static string GetPackageName(string discoveryJson) =>
+        GetPackageName(ParseDiscoveryJson(discoveryJson));
+
+    /// <summary>
+    /// Returns the name of the package generated from the given Discovery doc.
+    /// </summary>
+    public static string GetPackageName(RestDescription discoveryDoc)
+    {
+        // The code below is taken from PackageModel in the REST generator.
+        var className = (discoveryDoc.CanonicalName ?? discoveryDoc.Name).Replace(" ", "").ToMemberName();
+        string versionNoDots = discoveryDoc.Version.Replace('.', '_');
+        var camelizedPackagePath = discoveryDoc.PackagePath is null
+            ? ""
+            : string.Join('.', discoveryDoc.PackagePath.Split('/').Select(part => part.ToUpperCamelCase())) + ".";
+        return $"Google.Apis.{camelizedPackagePath}{className}.{versionNoDots}";
+    }
+}

Src/Tools/ToolUtilities/ToolUtilities.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net6.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+    <PackageReference Include="Google.Apis.Discovery.v1" Version="1.68.0" />
+  </ItemGroup>
+
+</Project>

Src/Tools/Tools.sln

@@ -11,7 +11,11 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "BuildGeneratedArgumentTrans
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DiscoveryDocUpdater", "DiscoveryDocUpdater\DiscoveryDocUpdater.csproj", "{4E0AE5D1-56DA-483D-989F-55750D2585ED}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PackageChecker", "PackageChecker\PackageChecker.csproj", "{6BA67CEC-7B2F-4A1C-B457-2C804C299D9E}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PackageChecker", "PackageChecker\PackageChecker.csproj", "{6BA67CEC-7B2F-4A1C-B457-2C804C299D9E}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ToolUtilities", "ToolUtilities\ToolUtilities.csproj", "{0F43325F-ED02-43F4-ACEE-07F129007552}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "UpdateReadmePackageList", "UpdateReadmePackageList\UpdateReadmePackageList.csproj", "{242B6A60-E733-4ADC-B9E5-BF307327B173}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -83,6 +87,30 @@ Global
 		{6BA67CEC-7B2F-4A1C-B457-2C804C299D9E}.Release|x64.Build.0 = Release|Any CPU
 		{6BA67CEC-7B2F-4A1C-B457-2C804C299D9E}.Release|x86.ActiveCfg = Release|Any CPU
 		{6BA67CEC-7B2F-4A1C-B457-2C804C299D9E}.Release|x86.Build.0 = Release|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Debug|x64.Build.0 = Debug|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Debug|x86.Build.0 = Debug|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Release|x64.ActiveCfg = Release|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Release|x64.Build.0 = Release|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Release|x86.ActiveCfg = Release|Any CPU
+		{0F43325F-ED02-43F4-ACEE-07F129007552}.Release|x86.Build.0 = Release|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Debug|x64.Build.0 = Debug|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Debug|x86.Build.0 = Debug|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Release|Any CPU.Build.0 = Release|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Release|x64.ActiveCfg = Release|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Release|x64.Build.0 = Release|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Release|x86.ActiveCfg = Release|Any CPU
+		{242B6A60-E733-4ADC-B9E5-BF307327B173}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

Src/Tools/UpdateReadmePackageList/PackageTableEntry.cs

@@ -0,0 +1,43 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Generated a list of packages with links to product documentation, NuGet,
+// and library reference documentation, within README.md.
+
+using Google.Apis.Discovery.v1.Data;
+using ToolUtilities;
+
+namespace UpdateReadmePackageList;
+
+internal class PackageTableEntry
+{
+    public string PackageName { get; }
+    public string NugetLink => $"https://www.nuget.org/packages/{PackageName}";
+    public string ReferenceDocsLink => $"https://googleapis.dev/dotnet/{PackageName}/latest/api/{PackageName}.html";
+    public string ApiDocsLink { get; }
+    public string ApiName { get; }
+
+    private PackageTableEntry(RestDescription discoveryDoc)
+    {
+        PackageName = Discovery.GetPackageName(discoveryDoc);
+        ApiDocsLink = discoveryDoc.DocumentationLink;
+        ApiName = $"{discoveryDoc.Title} {discoveryDoc.Version.Replace('.', '_')}";
+    }
+
+    public static PackageTableEntry Load(string discoveryFilePath) =>
+        new(Discovery.ParseDiscoveryJson(File.ReadAllText(discoveryFilePath)));
+
+    internal string ToMarkdown() =>
+        $"|[{ApiName}]({ApiDocsLink})|[{PackageName}]({NugetLink})|[Library documentation]({ReferenceDocsLink})|";
+}

Src/Tools/UpdateReadmePackageList/Program.cs

@@ -0,0 +1,54 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using UpdateReadmePackageList;
+
+// Everything before this line is preserved.
+// Everything after this line, but before the next empty line, is replaced.
+// Everything after the empty line after this line is preserved.
+const string TableHeaderSeparator = "|---|---|---|";
+
+if (args.Length != 2)
+{
+    Console.WriteLine("Arguments: <path-to-README.md> <path-to-discovery-directory>");
+    return 1;
+}
+
+string readmePath = args[0];
+string discoveryDirectory = args[1];
+
+var readmeLines = File.ReadAllLines(readmePath).ToList();
+int separatorIndex = readmeLines.IndexOf(TableHeaderSeparator);
+if (separatorIndex == -1)
+{
+    Console.WriteLine($"Unable to find header separator line in {readmePath}. Aborting.");
+    return 1;
+}
+
+var linesBeforeSeparator = readmeLines.Take(separatorIndex);
+var linesAfterTable = readmeLines.Skip(separatorIndex).SkipWhile(line => line != "");
+
+var tableEntries = Directory.GetFiles(discoveryDirectory, "*.json")
+    .Select(PackageTableEntry.Load)
+    .OrderBy(te => te.PackageName, StringComparer.Ordinal);
+
+var newReadmeLines = linesBeforeSeparator
+    .Append(TableHeaderSeparator)
+    .Concat(tableEntries.Select(te => te.ToMarkdown()))
+    .Concat(linesAfterTable)
+    .ToList(); // Evaluate eagerly before we start to write anything.
+
+File.WriteAllLines(readmePath, newReadmeLines);
+
+return 0;

Src/Tools/UpdateReadmePackageList/UpdateReadmePackageList.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net6.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\ToolUtilities\ToolUtilities.csproj" />
+  </ItemGroup>
+
+</Project>