Revamp index keywords.

Allow keywords to be set as "category/keyword", allowing an additional level of orgnization of the index. This allows to group similar keywords together, for example API keywords vs call chain keywords. Did a first pass on all the recipe keywords to make them more consistent and add missing call chains and API references. Also added a theme keyword to all recipe. Bug: N/A Test: existing Change-Id: Ia0fec27fe9a0b07b7255ba22862fdd507a81ef0b
android · Jan 10, 2024 · 8fc074b · 8fc074b
1 parent 7a0d529
commit 8fc074b
Show file tree

Hide file tree

Showing 20 changed files with 239 additions and 89 deletions.
diff --git a/...c/main/kotlin/com/google/android/gradle_recipe/converter/converters/RecursiveConverter.kt b/...c/main/kotlin/com/google/android/gradle_recipe/converter/converters/RecursiveConverter.kt
@@ -25,7 +25,11 @@ import java.nio.file.Path
 import java.util.*
 import kotlin.io.path.exists
 
-const val INDEX_METADATA_FILE = "README.md"
+private const val INDEX_METADATA_FILE = "README.md"
+
+private val THEME_ORDER = listOf("Themes", "APIs", "Call chains")
+
+private const val COMMA_DELIMITER = ", "
 
 /**
  * Recursive converter converts recipes from source of truth mode
@@ -39,7 +43,8 @@ class RecursiveConverter(
     private val branchRoot: Path,
 ) {
 
-    private val keywordsToRecipePaths = mutableMapOf<String, MutableList<IndexData>>()
+    // dual level map. The first level is the category of keywords, the 2nd is the keywords themselves
+    private val keywordMap = mutableMapOf<String, MutableMap<String, MutableList<IndexData>>>()
 
     private data class IndexData(
         val title: String,
@@ -65,7 +70,18 @@ class RecursiveConverter(
 
             if (conversionResult.result == ResultMode.SUCCESS) {
                 for (keyword in conversionResult.recipeData.keywords) {
-                    val list = keywordsToRecipePaths.computeIfAbsent(keyword) { mutableListOf() }
+
+                    // split the keyword in category/keyword if there is one
+                    val splits = keyword.split('/')
+                    val (category, kw) = when (splits.size) {
+                        1 -> "Others" to keyword
+                        2 -> splits[0] to splits[1]
+                        else -> error("Index entries should contain at most one '/' character: $keyword from $recipeFolder")
+                    }
+
+                    val secondaryMap = keywordMap.computeIfAbsent(category) { mutableMapOf() }
+
+                    val list = secondaryMap.computeIfAbsent(kw) { mutableListOf() }
                     list.add(
                         IndexData(
                             conversionResult.recipeData.indexName,
@@ -77,16 +93,15 @@ class RecursiveConverter(
         }
 
         // agpVersion is always true in release mode
-        writeRecipesIndexFile(keywordsToRecipePaths.toSortedMap(), destination, agpVersion!!)
+        writeRecipesIndexFile(keywordMap, destination, agpVersion!!)
     }
 
     private fun writeRecipesIndexFile(
-        keywordsToRecipePaths: MutableMap<String, MutableList<IndexData>>,
+        map: MutableMap<String, MutableMap<String, MutableList<IndexData>>>,
         destination: Path,
         agpVersion: String,
     ) {
         val builder = StringBuilder()
-        val commaDelimiter = ", "
         builder.appendLine("""
             # Recipes for AGP version `$agpVersion`
             This branch contains recipes compatible with AGP $agpVersion. If you want to find recipes
@@ -97,15 +112,17 @@ class RecursiveConverter(
         """.trimIndent())
         builder.appendLine("# Recipes Index")
 
-        keywordsToRecipePaths.keys.forEach { indexKeyword ->
-            builder.appendLine("* $indexKeyword - ")
-            val joiner = StringJoiner(commaDelimiter)
+        builder.appendLine("Index is organized in categories, offering different ways to reach the recipe you want.")
 
-            keywordsToRecipePaths[indexKeyword]?.forEach { data ->
-                joiner.add("[${data.title}](${data.link})")
-            }
+        // we want to process some known categories first, in a specific order that's not alphabetical
+        val unknownCategories = map.keys - THEME_ORDER
 
-            builder.appendLine(joiner.toString())
+        THEME_ORDER.forEach {
+            processCategory(builder, it, map)
+        }
+
+        unknownCategories.sorted().forEach { category ->
+            processCategory(builder, category, map)
         }
 
         builder.appendLine("""
@@ -131,4 +148,27 @@ class RecursiveConverter(
             destination.resolve(INDEX_METADATA_FILE).toUri()
         ).writeText(builder.toString())
     }
+
+    private fun processCategory(
+        stringBuilder: StringBuilder,
+        category: String,
+        map: MutableMap<String, MutableMap<String, MutableList<IndexData>>>
+    ) {
+        val secondaryMap = map[category] ?: return
+        if (secondaryMap.isEmpty()) return
+
+        stringBuilder.appendLine("## $category")
+
+        secondaryMap.keys.sorted().forEach { keyword ->
+            stringBuilder.append("* $keyword - ")
+
+            val joiner = StringJoiner(COMMA_DELIMITER)
+
+            secondaryMap[keyword]?.forEach { data ->
+                joiner.add("[${data.title}](${data.link})")
+            }
+
+            stringBuilder.appendLine(joiner.toString())
+        }
+    }
 }
diff --git a/recipes/addBuildTypeUsingDslFinalize/recipe_metadata.toml b/recipes/addBuildTypeUsingDslFinalize/recipe_metadata.toml
@@ -20,5 +20,7 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "finalizeDsl"
+    "Themes/DSL",
+    "APIs/DslLifecycle.finalizeDsl()",
+    "Call chains/androidComponents.finalizeDsl {}"
 ]
diff --git a/recipes/addCustomAsset/recipe_metadata.toml b/recipes/addCustomAsset/recipe_metadata.toml
@@ -19,6 +19,15 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "addGeneratedSourceDirectory",
-    "asset"
+    "Themes/Android Assets",
+    "Themes/Sources",
+    "APIs/SourceDirectories.addGeneratedSourceDirectory()",
+    "APIs/SingleArtifact.ASSETS",
+    "APIs/Artifacts.get()",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "APIs/Component.artifacts",
+    "APIs/Component.sources",
+    "Call chains/variant.sources.*.addGeneratedSourceDirectory()",
+    "Call chains/variant.artifacts.get()",
+    "Call chains/androidComponents.onVariants {}"
 ]
diff --git a/recipes/addCustomBuildConfigFields/recipe_metadata.toml b/recipes/addCustomBuildConfigFields/recipe_metadata.toml
@@ -19,7 +19,11 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "onVariant",
-    "BuildConfig",
-    "from Task"
+    "Call chains/androidComponents.onVariants {}",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/variant.buildConfigFields.put()",
+    "APIs/TaskProvider.map()",
+    "APIs/BuildConfigField()",
+    "APIs/Variant.buildConfigFields",
+    "APIs/MapProperty.put()"
 ]
diff --git a/recipes/addCustomSourceFolders/recipe_metadata.toml b/recipes/addCustomSourceFolders/recipe_metadata.toml
@@ -21,9 +21,14 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "onVariant",
+    "Themes/Sources",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/androidComponents.onVariants {}",
+    "Call chains/variant.sources.*.addGeneratedSourceDirectory()",
+    "Call chains/variant.sources.*.addStaticSourceDirectory()",
+    "APIs/SourceDirectories.addGeneratedSourceDirectory()",
+    "APIs/SourceDirectories.addStaticSourceDirectory()",
+    "APIs/Component.sources",
     "registerSourceType",
-    "addStaticSourceDirectory",
-    "addGeneratedSourceDirectory",
     "SourceDirectories.add",
 ]
diff --git a/recipes/addMultipleArtifact/recipe_metadata.toml b/recipes/addMultipleArtifact/recipe_metadata.toml
@@ -19,11 +19,15 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "onVariant",
-    "variant.artifacts.add",
-    "variant.artifacts.get",
-    "MultipleArtifact",
-    "MultipleArtifact.NATIVE_DEBUG_METADATA",
-    "SingleArtifact.BUNDLE",
+    "Themes/Artifact API",
+    "Call chains/androidComponents.onVariants {}",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "APIs/Component.artifacts",
+    "APIs/Artifacts.get()",
+    "APIs/Artifacts.add()",
+    "Call chains/variant.artifacts.add()",
+    "Call chains/variant.artifacts.get()",
+    "APIs/MultipleArtifact.NATIVE_DEBUG_METADATA",
+    "APIs/SingleArtifact.BUNDLE",
 ]
 
diff --git a/recipes/allProjectsApkAction/recipe_metadata.toml b/recipes/allProjectsApkAction/recipe_metadata.toml
@@ -19,9 +19,16 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-  "settings plugin",
-  "onVariant",
-  "All projects",
-  "SingleArtifact.APK",
-  "variant.artifacts.get",
+    "Call chains/androidComponents.onVariants {}",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/settings.gradle.beforeProject {}",
+    "APIs/Gradle.beforeProject()",
+    "APIs/Plugin<Settings>",
+    "Call chains/androidComponents.selector().withBuildType()",
+    "APIs/AndroidComponentsExtension.selector()",
+    "APIs/VariantSelector.withBuildType()",
+    "All projects",
+    "APIs/SingleArtifact.APK",
+    "Call chains/variant.artifacts.get()",
+    "APIs/Artifacts.get()"
 ]
diff --git a/recipes/appendToMultipleArtifact/recipe_metadata.toml b/recipes/appendToMultipleArtifact/recipe_metadata.toml
@@ -19,12 +19,16 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "onVariant",
-    "variant.artifacts.use",
-    "variant.artifacts.get",
-    "MultipleArtifact",
-    "MultipleArtifact.NATIVE_DEBUG_METADATA",
-    "OutOperationRequest.toAppendTo()",
-    "SingleArtifact.BUNDLE",
+    "Themes/Artifact API",
+    "Call chains/variant.artifacts.get()",
+    "Call chains/variant.artifacts.use().wiredWith().toAppendTo()",
+    "Call chains/androidComponents.onVariants {}",
+    "APIs/MultipleArtifact.NATIVE_DEBUG_METADATA",
+    "APIs/OutOperationRequest.toAppendTo()",
+    "APIs/SingleArtifact.BUNDLE",
+    "APIs/Artifacts.use()",
+    "APIs/Artifacts.get()",
+    "APIs/Component.artifacts",
+    "APIs/AndroidComponentsExtension.onVariants()"
 ]
 
diff --git a/recipes/createSingleArtifact/recipe_metadata.toml b/recipes/createSingleArtifact/recipe_metadata.toml
@@ -19,9 +19,15 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "onVariant",
-    "Manifest API",
-    "SingleArtifact.MERGED_MANIFEST",
-    "OutOperationRequest.toCreate",
-    "TaskBasedOperation.wiredWith(taskOutput)"
+    "Themes/Artifact API",
+    "Themes/Android Manifest",
+    "Call chains/androidComponents.onVariants {}",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "APIs/SingleArtifact.MERGED_MANIFEST",
+    "APIs/Artifacts.use()",
+    "APIs/OutOperationRequest.toCreate()",
+    "APIs/TaskBasedOperation.wiredWith()",
+    "Call chains/variant.artifacts.use().wiredWith().toCreate()",
+    "APIs/Component.artifacts",
+    "APIs/TaskProvider.flatMap()"
 ]
diff --git a/recipes/extendingAgp/recipe_metadata.toml b/recipes/extendingAgp/recipe_metadata.toml
@@ -20,7 +20,16 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-  "settings plugin",
-  "onVariant",
-  "extending AGP DSL",
+    "Themes/DSL",
+    "Call chains/androidComponents.onVariants {}",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/androidComponents.registerExtension()",
+    "APIs/AndroidComponentsExtension.registerExtension()",
+    "Call chains/DslExtension.Builder().extendProjectWith().extendBuildTypeWith().extendProductFlavorWith().build()",
+    "APIs/DslExtension.Builder.extendProjectWith()",
+    "APIs/DslExtension.Builder.extendBuildTypeWith()",
+    "APIs/DslExtension.Builder.extendProductFlavorWith()",
+    "APIs/DslExtension.Builder.build()",
+    "APIs/VariantExtensionConfig",
+    "Extending AGP DSL",
 ]
diff --git a/recipes/getMultipleArtifact/recipe_metadata.toml b/recipes/getMultipleArtifact/recipe_metadata.toml
@@ -19,8 +19,11 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "onVariant",
-    "variant.artifacts.getAll",
-    "MultipleArtifact",
-    "MultipleArtifact.MULTIDEX_KEEP_PROGUARD",
+    "Themes/Artifact API",
+    "Call chains/androidComponents.onVariants {}",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/variant.artifacts.getAll()",
+    "APIs/Component.artifacts",
+    "APIs/Artifacts.getAll()",
+    "APIs/MultipleArtifact.MULTIDEX_KEEP_PROGUARD",
 ]
diff --git a/recipes/getScopedArtifacts/recipe_metadata.toml b/recipes/getScopedArtifacts/recipe_metadata.toml
@@ -19,9 +19,15 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "onVariant",
-    "variant.artifacts.forScope",
-    "ScopedArtifacts.Scope.ALL",
-    "ScopedArtifacts.Scope.PROJECT",
-    "ScopedArtifact.CLASSES",
+    "Themes/Artifact API",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/androidComponents.onVariants {}",
+    "Call chains/variant.artifacts.forScope().use().toGet()",
+    "APIs/Component.artifacts",
+    "APIs/Artifacts.forScope()",
+    "APIs/ScopedArtifacts.Scope.ALL",
+    "APIs/ScopedArtifacts.Scope.PROJECT",
+    "APIs/ScopedArtifacts.use()",
+    "APIs/ScopedArtifact.CLASSES",
+    "APIs/ScopedArtifactsOperation.toGet()"
 ]
diff --git a/recipes/getSingleArtifact/recipe_metadata.toml b/recipes/getSingleArtifact/recipe_metadata.toml
@@ -19,7 +19,10 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "onVariant",
-    "variant.artifacts.get",
-    "SingleArtifact.BUNDLE",
+    "Themes/Artifact API",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/androidComponents.onVariants {}",
+    "APIs/Artifacts.get()",
+    "Call chains/variant.artifacts.get()",
+    "APIs/SingleArtifact.BUNDLE",
 ]
diff --git a/recipes/onVariants/recipe_metadata.toml b/recipes/onVariants/recipe_metadata.toml
@@ -20,6 +20,9 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "AndroidComponentsExtension.onVariants",
-    "variant.applicationId"
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/androidComponents.onVariants {}",
+    "Call chains/variant.applicationId",
+    "APIs/ApplicationVariant.applicationId",
+    "APIs/GeneratesApk.applicationId"
 ]
diff --git a/recipes/perVariantManifestPlaceholder/recipe_metadata.toml b/recipes/perVariantManifestPlaceholder/recipe_metadata.toml
@@ -20,8 +20,14 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-  "onVariant",
-  "Manifest API",
-  "Placeholders",
-  "SingleArtifact.MERGED_MANIFEST"
+    "Themes/Android Manifest",
+    "APIs/AndroidComponentsExtension.onVariants()",
+    "Call chains/androidComponents.onVariants {}",
+    "Call chains/variant.manifestPlaceholders.put()",
+    "APIs/Variant.manifestPlaceholders",
+    "APIs/MapProperty.put()",
+    "Placeholders",
+    "APIs/SingleArtifact.MERGED_MANIFEST",
+    "APIs/Artifacts.get()",
+    "Call chains/variant.artifacts.get()"
 ]
diff --git a/recipes/selectVariants/recipe_metadata.toml b/recipes/selectVariants/recipe_metadata.toml
@@ -21,9 +21,19 @@ tasks = [
 # All the relevant metadata fields to create an index based on language/API/etc'
 [indexMetadata]
 index = [
-    "AndroidComponentsExtension.beforeVariants",
-    "AndroidComponentsExtension.selector",
-    "VariantSelector.withFlavor",
-    "VariantSelector.withBuildType",
-    "VariantSelector.withName"
+    "APIs/AndroidComponentsExtension.beforeVariants()",
+    "Call chains/androidComponents.beforeVariants {}",
+    "APIs/AndroidComponentsExtension.selector()",
+    "APIs/VariantSelector.withFlavor()",
+    "Call chains/androidComponents.selector().withFlavor()",
+    "APIs/VariantSelector.withBuildType()",
+    "Call chains/androidComponents.selector().withBuildType()",
+    "APIs/VariantSelector.withName()",
+    "Call chains/androidComponents.selector().withName()",
+    "APIs/VariantSelector.all()",
+    "Call chains/androidComponents.selector().all()",
+    "APIs/VariantBuilder.minSdk",
+    "APIs/CanMinifyAndroidResourcesBuilder.shrinkResources",
+    "APIs/CanMinifyCodeBuilder.isMinifyEnabled",
+    "APIs/HasUnitTestBuilder.enableUnitTest",
 ]