feat: update library overview formatting

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.getApiDescription() + "\n\n";
+        "## Key Reference Links\n"
+            + "**"
+            + repoMetadata.getNamePretty()
+            + " Description:** "
+            + capitalizeFirstLetter(repoMetadata.getApiDescription())
+            + "\n\n";
 
     this.LIBRARY_OVERVIEW_KEY_REFERENCE_TABLE =
         "<table>\n"
@@ -108,17 +113,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 =
-        "<div>\n"
-            + "<devsite-selector>\n"
-            + "<section>\n"
-            + "<h3>Maven</h3>\n"
-            + "<p>Import the BOM in the <code>dependencyManagement</code> section of your <code>pom.xml</code> file.\n"
+        "### Maven\n"
+            + "Import the BOM in the <code>dependencyManagement</code> section of your <code>pom.xml</code> file.\n"
             + "Include specific artifacts you depend on in the <code>dependencies</code> section, but don't\n"
-            + "specify the artifacts' versions in the <code>dependencies</code> section.</p>\n"
+            + "specify the artifacts' versions in the <code>dependencies</code> section.\n"
             + "\n"
-            + "<p>The example below demonstrates how you would import the BOM and include the <code>google-cloud-apikeys</code>\n"
-            + "artifact.</p>\n"
+            + "The example below demonstrates how you would import the BOM and include the <code>"
+            + repoMetadata.getArtifactId()
+            + "</code> artifact.\n"
             + "<pre class=\"prettyprint lang-xml devsite-click-to-copy\">\n"
             + "&lt;dependencyManagement&gt;\n"
             + " &lt;dependencies&gt;\n"
@@ -141,53 +146,46 @@ public LibraryOverviewFile(
             + "&lt;/artifactId&gt;\n"
             + " &lt;/dependency&gt;\n"
             + "&lt;/dependencies&gt;\n"
-            + "</pre>\n"
-            + "</section>\n"
-            + "<section>\n"
-            + "<h3>Gradle</h3>\n"
-            + "<p>BOMs are supported by default in Gradle 5.x or later. Add a <code>platform</code>\n"
+            + "</pre>\n\n"
+            + "### Gradle\n"
+            + "BOMs are supported by default in Gradle 5.x or later. Add a <code>platform</code>\n"
             + "dependency on <code>com.google.cloud:libraries-bom</code> and remove the version from the\n"
-            + "dependency declarations in the artifact's <code>build.gradle</code> file.</p>\n"
+            + "dependency declarations in the artifact's <code>build.gradle</code> file.\n"
             + "\n"
-            + "<p>The example below demonstrates how you would import the BOM and include the <code>google-cloud-apikeys</code>\n"
-            + "artifact.</p>\n"
+            + "The example below demonstrates how you would import the BOM and include the <code>"
+            + repoMetadata.getArtifactId()
+            + "</code> artifact.\n"
             + "<pre class=\"prettyprint lang-Groovy devsite-click-to-copy\">\n"
             + "implementation platform(&#39;com.google.cloud:libraries-bom:"
             + librariesBomVersion
             + "&#39;)\n"
             + "implementation &#39;"
             + repoMetadata.getDistributionName()
             + "&#39;\n"
-            + "</pre>\n"
-            + "<p>The <code>platform</code> and <code>enforcedPlatform</code> keywords supply dependency versions\n"
+            + "</pre>\n\n"
+            + "The <code>platform</code> and <code>enforcedPlatform</code> keywords supply dependency versions\n"
             + "declared in a BOM. The <code>enforcedPlatform</code> keyword enforces the dependency\n"
-            + "versions declared in the BOM and thus overrides what you specified.</p>\n"
-            + "\n"
-            + "<p>For more details of the <code>platform</code> and <code>enforcedPlatform</code> keywords Gradle 5.x or higher, see\n"
-            + "<a href=\"https://docs.gradle.org/current/userguide/platforms.html#sub:bom_import\">Gradle: Importing Maven BOMs</a>.</p>\n"
+            + "versions declared in the BOM and thus overrides what you specified.\n\n"
+            + "For more details of the <code>platform</code> and <code>enforcedPlatform</code> 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"
-            + "<p>If you're using Gradle 4.6 or later, add\n"
+            + "If you're using Gradle 4.6 or later, add\n"
             + "<code>enableFeaturePreview('IMPROVED_POM_SUPPORT')</code> to your <code>settings.gradle</code> file. For details, see\n"
-            + "<a href=\"https://docs.gradle.org/4.6/release-notes.html#bom-import\">Gradle 4.6 Release Notes: BOM import</a>.\n"
-            + "Versions of Gradle earlier than 4.6 don't support BOMs.</p>\n"
-            + "</section>\n"
-            + "<section>\n"
-            + "<h3>SBT</h3>\n"
-            + "<p>SBT <a href=\"https://github.com/sbt/sbt/issues/4531\">doesn't support BOMs</a>. 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.</p>\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"
-            + "<a href=\"https://storage.googleapis.com/cloud-opensource-java-dashboard/com.google.cloud/libraries-bom/index.html\">dashboard</a>\n"
-            + "and set the versions manually.</p>\n"
-            + "<p>To use the latest version of this library, add this to your dependencies:</p>\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"
             + "<pre class=\"prettyprint lang-Scala devsite-click-to-copy\">\n"
             + "libraryDependencies += &quot;com.google.cloud&quot; % &quot;"
             + repoMetadata.getArtifactId()
             + "&quot; % &quot;"
             + artifactVersion
             + "&quot;\n"
-            + "</pre>\n"
-            + "</section>\n"
-            + "</devsite-selector>\n"
-            + "</div>\n\n";
+            + "</pre>\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 +218,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;

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.
 
 <table>
    <tr>
@@ -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).
 
-<div>
-<devsite-selector>
-<section>
-<h3>Maven</h3>
-<p>Import the BOM in the <code>dependencyManagement</code> section of your <code>pom.xml</code> file.
+### Maven
+Import the BOM in the <code>dependencyManagement</code> section of your <code>pom.xml</code> file.
 Include specific artifacts you depend on in the <code>dependencies</code> section, but don't
-specify the artifacts' versions in the <code>dependencies</code> section.</p>
+specify the artifacts' versions in the <code>dependencies</code> section.
 
-<p>The example below demonstrates how you would import the BOM and include the <code>google-cloud-apikeys</code>
-artifact.</p>
+The example below demonstrates how you would import the BOM and include the <code>google-cloud-apikeys</code> artifact.
 <pre class="prettyprint lang-xml devsite-click-to-copy">
 &lt;dependencyManagement&gt;
  &lt;dependencies&gt;
@@ -57,44 +53,39 @@ artifact.</p>
  &lt;/dependency&gt;
 &lt;/dependencies&gt;
 </pre>
-</section>
-<section>
-<h3>Gradle</h3>
-<p>BOMs are supported by default in Gradle 5.x or later. Add a <code>platform</code>
+
+### Gradle
+BOMs are supported by default in Gradle 5.x or later. Add a <code>platform</code>
 dependency on <code>com.google.cloud:libraries-bom</code> and remove the version from the
-dependency declarations in the artifact's <code>build.gradle</code> file.</p>
+dependency declarations in the artifact's <code>build.gradle</code> file.
 
-<p>The example below demonstrates how you would import the BOM and include the <code>google-cloud-apikeys</code>
-artifact.</p>
+The example below demonstrates how you would import the BOM and include the <code>google-cloud-apikeys</code> artifact.
 <pre class="prettyprint lang-Groovy devsite-click-to-copy">
 implementation platform(&#39;com.google.cloud:libraries-bom:26.19.0&#39;)
 implementation &#39;com.google.cloud:google-cloud-apikeys&#39;
 </pre>
-<p>The <code>platform</code> and <code>enforcedPlatform</code> keywords supply dependency versions
+
+The <code>platform</code> and <code>enforcedPlatform</code> keywords supply dependency versions
 declared in a BOM. The <code>enforcedPlatform</code> keyword enforces the dependency
-versions declared in the BOM and thus overrides what you specified.</p>
+versions declared in the BOM and thus overrides what you specified.
 
-<p>For more details of the <code>platform</code> and <code>enforcedPlatform</code> keywords Gradle 5.x or higher, see
-<a href="https://docs.gradle.org/current/userguide/platforms.html#sub:bom_import">Gradle: Importing Maven BOMs</a>.</p>
+For more details of the <code>platform</code> and <code>enforcedPlatform</code> keywords Gradle 5.x or higher, see
+[Gradle: Importing Maven BOMs](https://docs.gradle.org/current/userguide/platforms.html#sub:bom_import).
 
-<p>If you're using Gradle 4.6 or later, add
+If you're using Gradle 4.6 or later, add
 <code>enableFeaturePreview('IMPROVED_POM_SUPPORT')</code> to your <code>settings.gradle</code> file. For details, see
-<a href="https://docs.gradle.org/4.6/release-notes.html#bom-import">Gradle 4.6 Release Notes: BOM import</a>.
+[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.</p>
-</section>
-<section>
-<h3>SBT</h3>
-<p>SBT <a href="https://github.com/sbt/sbt/issues/4531">doesn't support BOMs</a>. 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
-<a href="https://storage.googleapis.com/cloud-opensource-java-dashboard/com.google.cloud/libraries-bom/index.html">dashboard</a>
-and set the versions manually.</p>
-<p>To use the latest version of this library, add this to your dependencies:</p>
+[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:
 <pre class="prettyprint lang-Scala devsite-click-to-copy">
 libraryDependencies += &quot;com.google.cloud&quot; % &quot;google-cloud-apikeys&quot; % &quot;0.18.0&quot;
 </pre>
-</section>
-</devsite-selector>
-</div>
 
 ## Which version should I use?
 For this library, we recommend using API version v1 for new applications.