-
Notifications
You must be signed in to change notification settings - Fork 529
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Add a package table to README.md #2864
Merged
Merged
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
7b8fe8d
refactor: Extract code for Discovery doc handling to common library
jskeet 71707ed
tools: Add tooling to generate package table in README.md
jskeet aedae34
chore: Run package table generation tool
jskeet baac389
chore: Regenerate the package table in README.md when autogenerating
jskeet 5abb638
chore: Fix comment/license issues
jskeet File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | ||
|
|
||
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| 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}"; | ||
| } | ||
| } |
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| | ||
| 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})|"; | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| // 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. | ||
|
|
||
| // Translates the arguments from BuildGenerated.sh into directories containing | ||
| // libraries. This is primarily for the sake of being able to accept Discovery file | ||
| // paths as reported by earlier phases of the build pipeline. See BuildGenerated.sh | ||
| // 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 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; |
14 changes: 14 additions & 0 deletions
14
Src/Tools/UpdateReadmePackageList/UpdateReadmePackageList.csproj
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: License