From 604829c7e327bb82e38fed65a1921470f7c56a17 Mon Sep 17 00:00:00 2001 From: Alice Li Date: Tue, 28 Nov 2023 10:53:26 -0500 Subject: [PATCH 1/2] feat: update library overview formatting --- .../microsoft/model/LibraryOverviewFile.java | 77 ++++++++++--------- .../expected-generated-files/overview.md | 55 ++++++------- 2 files changed, 63 insertions(+), 69 deletions(-) diff --git a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java index ced58cc9..d4687049 100644 --- a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java +++ b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java @@ -55,7 +55,7 @@ public LibraryOverviewFile( "# " + repoMetadata.getArtifactId() + " overview (" + artifactVersion + ")\n\n"; this.LIBRARY_OVERVIEW_KEY_REFERENCE_HEADER = - "## Key Reference Links\n" + repoMetadata.getApiDescription() + "\n\n"; + "## Key Reference Links\n" + "**" + repoMetadata.getNamePretty() + " Description:** " + capitalizeFirstLetter(repoMetadata.getApiDescription()) + "\n\n"; this.LIBRARY_OVERVIEW_KEY_REFERENCE_TABLE = "\n" @@ -108,17 +108,17 @@ public LibraryOverviewFile( + "set previously. For more information about\n" + "BOMs, see [Google Cloud Platform Libraries BOM](https://cloud.google.com/java/docs/bom).\n\n"; + // When b/312765900 is implemented, then refactor this section to use the devsite-selector + // format. Current format is a workaround so the sanitizer doesn't remove the content. this.LIBRARY_OVERVIEW_CLIENT_INSTALLATION_SECTION = - "
\n" - + "\n" - + "
\n" - + "

Maven

\n" - + "

Import the BOM in the dependencyManagement section of your pom.xml file.\n" + "### Maven\n" + + "Import the BOM in the dependencyManagement section of your pom.xml file.\n" + "Include specific artifacts you depend on in the dependencies section, but don't\n" - + "specify the artifacts' versions in the dependencies section.

\n" + + "specify the artifacts' versions in the dependencies section.\n" + "\n" - + "

The example below demonstrates how you would import the BOM and include the google-cloud-apikeys\n" - + "artifact.

\n" + + "The example below demonstrates how you would import the BOM and include the " + + repoMetadata.getArtifactId() + + " artifact.\n" + "
\n"
             + "<dependencyManagement>\n"
             + " <dependencies>\n"
@@ -141,16 +141,15 @@ public LibraryOverviewFile(
             + "</artifactId>\n"
             + " </dependency>\n"
             + "</dependencies>\n"
-            + "
\n" - + "
\n" - + "
\n" - + "

Gradle

\n" - + "

BOMs are supported by default in Gradle 5.x or later. Add a platform\n" + + "\n\n" + + "### Gradle\n" + + "BOMs are supported by default in Gradle 5.x or later. Add a platform\n" + "dependency on com.google.cloud:libraries-bom and remove the version from the\n" - + "dependency declarations in the artifact's build.gradle file.

\n" + + "dependency declarations in the artifact's build.gradle file.\n" + "\n" - + "

The example below demonstrates how you would import the BOM and include the google-cloud-apikeys\n" - + "artifact.

\n" + + "The example below demonstrates how you would import the BOM and include the " + + repoMetadata.getArtifactId() + + " artifact.\n" + "
\n"
             + "implementation platform('com.google.cloud:libraries-bom:"
             + librariesBomVersion
@@ -158,36 +157,30 @@ public LibraryOverviewFile(
             + "implementation '"
             + repoMetadata.getDistributionName()
             + "'\n"
-            + "
\n" - + "

The platform and enforcedPlatform keywords supply dependency versions\n" + + "\n\n" + + "The platform and enforcedPlatform keywords supply dependency versions\n" + "declared in a BOM. The enforcedPlatform keyword enforces the dependency\n" - + "versions declared in the BOM and thus overrides what you specified.

\n" + + "versions declared in the BOM and thus overrides what you specified.\n\n" + + "For more details of the platform and enforcedPlatform keywords Gradle 5.x or higher, see\n" + + "[Gradle: Importing Maven BOMs](https://docs.gradle.org/current/userguide/platforms.html#sub:bom_import).\n" + "\n" - + "

For more details of the platform and enforcedPlatform keywords Gradle 5.x or higher, see\n" - + "Gradle: Importing Maven BOMs.

\n" - + "\n" - + "

If you're using Gradle 4.6 or later, add\n" + + "If you're using Gradle 4.6 or later, add\n" + "enableFeaturePreview('IMPROVED_POM_SUPPORT') to your settings.gradle file. For details, see\n" - + "Gradle 4.6 Release Notes: BOM import.\n" - + "Versions of Gradle earlier than 4.6 don't support BOMs.

\n" - + "
\n" - + "
\n" - + "

SBT

\n" - + "

SBT doesn't support BOMs. You can find\n" + + "[Gradle 4.6 Release Notes: BOM import](https://docs.gradle.org/4.6/release-notes.html#bom-import).\n" + + "Versions of Gradle earlier than 4.6 don't support BOMs.

\n\n" + + "### SBT\n" + + "SBT [doesn't support BOMs](https://github.com/sbt/sbt/issues/4531). You can find\n" + "recommended versions of libraries from a particular BOM version on the\n" - + "dashboard\n" - + "and set the versions manually.

\n" - + "

To use the latest version of this library, add this to your dependencies:

\n" + + "[dashboard](https://storage.googleapis.com/cloud-opensource-java-dashboard/com.google.cloud/libraries-bom/index.html)\n" + + "and set the versions manually.\n" + + "To use the latest version of this library, add this to your dependencies:\n" + "
\n"
             + "libraryDependencies += "com.google.cloud" % ""
             + repoMetadata.getArtifactId()
             + "" % ""
             + artifactVersion
             + ""\n"
-            + "
\n" - + "
\n" - + "\n" - + "
\n\n"; + + "\n\n"; // Some client libraries do not have an underlying API service (e.g. // google-cloud-logging-logback, google-cloud-storage-nio, google-cloud-spanner-jdbc), hence @@ -220,6 +213,16 @@ public String getFileContent() { + LIBRARY_OVERVIEW_PACKAGE_SELECTION_SECTION; } + @JsonIgnore + private static String capitalizeFirstLetter(String string) { + if (string == null || string.isEmpty()) { + return string; // Return unchanged if input is null or empty + } + + // Capitalize the first character and append the rest of the string + return string.substring(0, 1).toUpperCase() + string.substring(1); + } + @JsonIgnore public String getFileNameWithPath() { return outputPath + File.separator + fileName; diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md index d0a56d41..9ae046d5 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md @@ -1,7 +1,7 @@ # google-cloud-apikeys overview (0.18.0) ## Key Reference Links -API Keys lets you create and manage your API keys for your projects. +**API Keys API Description:** API Keys lets you create and manage your API keys for your projects.
@@ -27,16 +27,12 @@ the BOM to specify dependency versions. Be sure to remove any versions that you set previously. For more information about BOMs, see [Google Cloud Platform Libraries BOM](https://cloud.google.com/java/docs/bom). -
- -
-

Maven

-

Import the BOM in the dependencyManagement section of your pom.xml file. +### Maven +Import the BOM in the dependencyManagement section of your pom.xml file. Include specific artifacts you depend on in the dependencies section, but don't -specify the artifacts' versions in the dependencies section.

+specify the artifacts' versions in the dependencies section. -

The example below demonstrates how you would import the BOM and include the google-cloud-apikeys -artifact.

+The example below demonstrates how you would import the BOM and include the google-cloud-apikeys artifact. 
 <dependencyManagement>
  <dependencies>
@@ -57,44 +53,39 @@ artifact.

  </dependency>
 </dependencies>
-
-
-

Gradle

-

BOMs are supported by default in Gradle 5.x or later. Add a platform + +### Gradle +BOMs are supported by default in Gradle 5.x or later. Add a platform dependency on com.google.cloud:libraries-bom and remove the version from the -dependency declarations in the artifact's build.gradle file.

+dependency declarations in the artifact's build.gradle file. -

The example below demonstrates how you would import the BOM and include the google-cloud-apikeys -artifact.

+The example below demonstrates how you would import the BOM and include the google-cloud-apikeys artifact. 
 implementation platform('com.google.cloud:libraries-bom:26.19.0')
 implementation 'com.google.cloud:google-cloud-apikeys'
-

The platform and enforcedPlatform keywords supply dependency versions + +The platform and enforcedPlatform keywords supply dependency versions declared in a BOM. The enforcedPlatform keyword enforces the dependency -versions declared in the BOM and thus overrides what you specified.

+versions declared in the BOM and thus overrides what you specified. -

For more details of the platform and enforcedPlatform keywords Gradle 5.x or higher, see -Gradle: Importing Maven BOMs.

+For more details of the platform and enforcedPlatform keywords Gradle 5.x or higher, see +[Gradle: Importing Maven BOMs](https://docs.gradle.org/current/userguide/platforms.html#sub:bom_import). -

If you're using Gradle 4.6 or later, add +If you're using Gradle 4.6 or later, add enableFeaturePreview('IMPROVED_POM_SUPPORT') to your settings.gradle file. For details, see -Gradle 4.6 Release Notes: BOM import. +[Gradle 4.6 Release Notes: BOM import](https://docs.gradle.org/4.6/release-notes.html#bom-import). Versions of Gradle earlier than 4.6 don't support BOMs.

-
-
-

SBT

-

SBT doesn't support BOMs. You can find + +### SBT +SBT [doesn't support BOMs](https://github.com/sbt/sbt/issues/4531). You can find recommended versions of libraries from a particular BOM version on the -dashboard -and set the versions manually.

-

To use the latest version of this library, add this to your dependencies:

+[dashboard](https://storage.googleapis.com/cloud-opensource-java-dashboard/com.google.cloud/libraries-bom/index.html) +and set the versions manually. +To use the latest version of this library, add this to your dependencies: 
 libraryDependencies += "com.google.cloud" % "google-cloud-apikeys" % "0.18.0"
-
- -
## Which version should I use? For this library, we recommend using API version v1 for new applications. From 0692277a52e89fa7f473556dd5dfb7621da290be Mon Sep 17 00:00:00 2001 From: Alice Li Date: Tue, 28 Nov 2023 11:11:50 -0500 Subject: [PATCH 2/2] fix lint --- .../main/java/com/microsoft/model/LibraryOverviewFile.java | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java index d4687049..52940b0b 100644 --- a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java +++ b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java @@ -55,7 +55,12 @@ public LibraryOverviewFile( "# " + repoMetadata.getArtifactId() + " overview (" + artifactVersion + ")\n\n"; this.LIBRARY_OVERVIEW_KEY_REFERENCE_HEADER = - "## Key Reference Links\n" + "**" + repoMetadata.getNamePretty() + " Description:** " + capitalizeFirstLetter(repoMetadata.getApiDescription()) + "\n\n"; + "## Key Reference Links\n" + + "**" + + repoMetadata.getNamePretty() + + " Description:** " + + capitalizeFirstLetter(repoMetadata.getApiDescription()) + + "\n\n"; this.LIBRARY_OVERVIEW_KEY_REFERENCE_TABLE = "
\n"