Add extractSnippets Gradle task and plugin to export transformed snippets - #1037
Conversation
1c8382f to
4d837ca
Compare
…pets Adds a custom extractSnippets task and plugin in buildSrc to parse region tags, handle [START_EXCLUDE] blocks (with language-specific ellipses comments including block comments), strip region delimiters, normalize CRLF/LF line endings, and normalize indentation via trimIndent(). Supports per-submodule execution, multiplatform source sets (including .kt, .java, .xml, .json, .proto, .swift, .kts, .gradle, .pro), duplicate tag detection, explicit UTF-8 I/O, output directory purging, and tag (-Ptag=...) / package (-Ppackage=...) filtering. Includes a golden unit test suite in buildSrc and diagnostic warning reporting.
4d837ca to
e523e4b
Compare
bsagmoe
changed the title
|
Thanks Ben! I haven't reviewed the code yet but could you clarify the use case you're envisioning here? "making it easy to use them as the source for inline code blocks while staging new or updated documentation." Also could you share an example of what the output file will look like? Is it a list of region tags for that module? |
|
An example would be I'm authoring some new documentation for returning results in Nav 3 and am adding snippets in #1035. But because those snippets aren't yet available in the GitHub mirror that DAC pulls from, it's easier to inline them in the overall DAC CL while I'm working on it to see how the final page will look. This build script makes it easier to author the snippets just in the snippets repo and copy them over to inline code in the DAC CL. For example, with this as the snippet file: // compose/snippets/src/main/java/com/example/compose/snippets/navigation3/decorators/DecoratorSnippets.kt
@Composable
fun DecoratorsResultEventBus() {
// [START android_compose_navigation3_decorator_result_hoist]
val resultEventBus = rememberResultEventBus()
NavDisplay(
// [START_EXCLUDE]
backStack = rememberNavBackStack(Home),
entryProvider = entryProvider<NavKey> {
entry<Home> { Text("Welcome to Nav3") }
},
// [END_EXCLUDE]
entryDecorators = listOf(
rememberSaveableStateHolderNavEntryDecorator<NavKey>(),
rememberResultEventBusNavEntryDecorator<NavKey>(resultEventBus = resultEventBus)
)
)
// [END android_compose_navigation3_decorator_result_hoist]
}Running val resultEventBus = rememberResultEventBus()
NavDisplay(
// ...
entryDecorators = listOf(
rememberSaveableStateHolderNavEntryDecorator<NavKey>(),
rememberResultEventBusNavEntryDecorator<NavKey>(resultEventBus = resultEventBus)
)
)Which I (or an agent) can easily copy-paste into the DAC files. It also sounds like this would be useful for including snippets in skills during the eval phase before they're fully published on DAC. |
kkuan2011
left a comment
kkuan2011
left a comment
There was a problem hiding this comment.
Thanks for the additional context, Ben! Cool that it can show a rendered version of what the snippet would look like on the webpage.
If this addition doesn't affect build time for people using snippets repo, then sounds good to submit. Otherwise, let's discuss more.
|
Also is there any way to get the snippet-bot check to pass? I saw that you added the exclusion and I tried to get it to run again by clicking the checkbox "Refresh this comment" but that didn't seem to work. |
Yeah, tried that as well. Dug into it and it looks like it always runs against the current main branch |
- Move buildSrc extraction sources into com.android.snippets.build.extractor package. - Add @option annotations to enable double-dash CLI arguments (--tag, --package). - Configure property conventions in plugin task registration for Configuration Cache compatibility. - Remove test directory exclusions to scan documentation test snippets. - Require tag names in ANY_DELIMITER_REGEX and remove early-return in END_EXCLUDE handling. - Replace external DevSite references with generic documentation terminology. - Add unit tests for multi-exclude, warning reporting branches, and tag filtering isolation.
2 participants
Summary
Adds an
extractSnippetsGradle plugin inbuildSrcto extract snippets and transform them to match rendering on developer.android.com. Output files are saved to each module'sbuild/extracted-snippets/directory, making it easy to use them as the source for inline code blocks while staging new or updated documentation.Details:
[START <tag>]regions, handles[START_EXCLUDE]comments and silent blocks, strips inner delimiters, and normalizes indentation the same way the DevSite processor does.-Ptag=<name>or-Ppackage=<path>.Usage: