Skip to content

Commit

Permalink
feat: update library overview formatting (#226)
Browse files Browse the repository at this point in the history 
* feat: update library overview formatting

* fix lint
  • Loading branch information
@alicejli
alicejli authored Nov 28, 2023
1 parent 489aca9 commit 3aa99c2
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 69 deletions.
82 changes: 45 additions & 37 deletions third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand All @@ -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
Expand Down Expand Up @@ -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;
Expand Down
55 changes: 23 additions & 32 deletions ...rty/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md
View file
Original file line number Diff line number Diff line change
@@ -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>
Expand All @@ -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;
Expand All @@ -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.
Expand Down

0 comments on commit 3aa99c2

Please sign in to comment.