From 9bd7434c0c4416c2600406e019e99057859c89de Mon Sep 17 00:00:00 2001 From: Rafael Tonholo Date: Sun, 24 Nov 2024 08:12:57 -0400 Subject: [PATCH] docs: add gradle plugin docs --- .editorconfig | 3 + svg-to-compose-gradle-plugin/README.md | 236 ++++++++++++++++++ svg-to-compose-gradle-plugin/build.gradle.kts | 2 + 3 files changed, 241 insertions(+) create mode 100644 svg-to-compose-gradle-plugin/README.md diff --git a/.editorconfig b/.editorconfig index e7539259..67f72a32 100644 --- a/.editorconfig +++ b/.editorconfig @@ -150,3 +150,6 @@ ij_yaml_spaces_within_brackets = true [*.svg] indent_size = 2 + +[*.md] +max_line_length = 80 diff --git a/svg-to-compose-gradle-plugin/README.md b/svg-to-compose-gradle-plugin/README.md new file mode 100644 index 00000000..a586cf49 --- /dev/null +++ b/svg-to-compose-gradle-plugin/README.md @@ -0,0 +1,236 @@ +# SVG/XML to Compose Gradle Plugin + +## Table of Contents + +- [Motivation](#motivation) +- [Installation](#installation) +- [How It Works](#how-it-works) +- [Configuration](#configuration) + +## Motivation + +The **SVG/XML to Compose** Gradle Plugin simplifies the process of converting +SVG and Android Vector Drawable (AVG/XML) files into Jetpack Compose +`ImageVector` properties. Manually converting vector assets can be tedious and +error-prone, especially in projects with a large number of icons. This plugin +automates the conversion process, ensuring consistency and saving valuable +development time. + +By using the **SVG/XML to Compose** plugin, you can automate and customize the +integration of vector assets into your Compose projects, ensuring a more +efficient and error-free workflow. + +## Installation + +The **SVG/XML to Compose** plugin is available on +[Maven Central](https://search.maven.org/). You can apply it to your project +using the Plugins DSL or include it via buildSrc or build conventions. + +### Applying via Plugins DSL + +Add the plugin to your module's `build.gradle.kts` file: + +```kotlin +plugins { + id("dev.tonholo.s2c") version "" +} +``` + +Ensure that Maven Central is included in your plugin repositories. In most +cases, Gradle includes Maven Central by default. If not, add the following to +your settings.gradle.kts or build.gradle.kts: + +```kotlin +pluginManagement { + repositories { + mavenCentral() + gradlePluginPortal() + } +} +``` + +### Applying via buildSrc or Build Conventions + +If you prefer to manage your plugins through buildSrc or a custom build +conventions plugin, you can include Svg2Compose as a dependency. + +#### Using buildSrc + +1. Create buildSrc Directory: If it doesn’t exist, create a buildSrc directory + at the root of your project. +2. Add Dependencies: In buildSrc/build.gradle.kts, add the plugin as a + dependency: + +```kotlin +repositories { + mavenCentral() +} + +dependencies { + implementation("dev.tonholo.s2c:svg-to-compose-gradle-plugin:") +} +``` + +3. Apply the Plugin: In your module’s build.gradle.kts, apply the plugin using + the plugins block: + +```kotlin +plugins { + id("dev.tonholo.s2c") +} +``` + +## How It Works + +The plugin automates the conversion of SVG and Android Vector Drawable (AVG) +files into Jetpack Compose `ImageVector` objects. It scans the specified +directories, processes each icon according to your configuration, and generates +the corresponding Compose code. + +When a Kotlin Compile task is initiated in your project, the plugin checks for +changes in the specified icons. Its built-in cache determines whether an icon +needs to be regenerated or deleted from the original folder to ensure effective +icon generation. + +In addition, whenever a change is made to the plugin configuration, the cache is +invalidated to regenerate the icons reflecting the changes in the next build. + +### Processing Flow + +1. **Configuration Parsing**: The plugin reads your configurations defined in + the `svgToCompose` extension. +2. **Icon Scanning**: It scans the specified directories for SVG and AVG files. +3. **Icon Processing**: Each icon is processed with the specified options (e.g., + optimization, minification). +4. **Code Generation**: Generates `ImageVector` objects in the specified + package. +5. **Build Integration**: The generated code is integrated into your project + during the build process. + +## Configuration + +After applying the plugin, configure it in your `build.gradle.kts` file using +the `svgToCompose` extension. This extension allows you to specify how the +SVG/AVG files should be processed and converted. + +### Basic Configuration + +```kotlin +svgToCompose { + processor { + val icons by creating { + from(layout.projectDirectory.dir("src/main/resources/icons")) + destinationPackage("com.example.app.ui.icons") + optimize(true) + recursive() + icons { + theme("com.example.app.ui.theme.AppTheme") + minify() + exclude(".*_exclude\\.svg".toRegex()) + mapIconNameTo { iconName -> + iconName.replace("_filled", "") + } + } + } + } +} +``` + +### Common Configuration + +You can define common settings for all processors: + +```kotlin +svgToCompose { + processor { + common { + optimize(true) + recursive() + icons { + minify() + } + } + + val outlinedIcons by creating { + from(layout.projectDirectory.dir("src/main/resources/icons/outlined")) + destinationPackage("com.example.app.ui.icons.outlined") + } + + val filledIcons by creating { + from(layout.projectDirectory.dir("src/main/resources/icons/filled")) + destinationPackage("com.example.app.ui.icons.filled") + } + } +} +``` + +#### Configuration Options + +**svgToCompose Extension** + +- **processor**: Configures individual processors for different sets of icons. + +**Processor Configuration** + +- **from(Directory)**: Specifies the directory containing the SVG/AVG icons. +- **destinationPackage(String)**: The package where the generated `ImageVector` + objects will reside. +- **optimize(Boolean)**: Enables optimization of the generated code. +- **recursive()**: Enables recursive search for icons in subdirectories. +- **maxDepth(Int)**: Sets the maximum depth for recursive search. +- **icons { ... }**: Configures icon-specific parsing options. + +**Icon Parser Configuration** + +Within the `icons` block, you can customize how icons are processed: + +- **theme(String)**: Specifies the fully qualified name of the theme for + previews. +- **minify()**: Removes comments and extra spaces to reduce code size. +- **noPreview()**: Disables the generation of preview images. +- **makeInternal()**: Adds the `internal` modifier to the generated + `ImageVector`. +- **receiverType(String)**: Sets a receiver type for the `ImageVector` property. +- **addToMaterialIcons()**: Uses Material `Icons` as the receiver type. +- **mapIconNameTo((String) -> String)**: Customizes icon names using a mapping + function. +- **exclude(vararg Regex)**: Excludes icons based on filename patterns. +- **persist()**: Persists generated files in the source set (use with caution). + +### Enabling Parallel Processing (Experimental) + +You can enable experimental parallel processing to speed up icon generation: + +```kotlin +svgToCompose { + processor { + @OptIn(dev.tonholo.s2c.annotations.ExperimentalParallelProcessing) + useParallelism(parallelism = 4) + // Processor configurations... + } +} +``` + +**Note**: This feature is experimental and may have unexpected behavior. + +### Persistent Generation + +To persist generated icons in your source code (overwriting existing files): + +```kotlin +svgToCompose { + processor { + val persistentIcons by creating { + // Processor configurations... + icons { + @OptIn(dev.tonholo.s2c.annotations.DelicateSvg2ComposeApi) + persist() + } + } + } +} +``` + +> [!WARNING] +> This is a delicate operation. Use `persist()` only if you're sure +> you want to overwrite existing files in your source set. diff --git a/svg-to-compose-gradle-plugin/build.gradle.kts b/svg-to-compose-gradle-plugin/build.gradle.kts index 197d099b..be89ed8a 100644 --- a/svg-to-compose-gradle-plugin/build.gradle.kts +++ b/svg-to-compose-gradle-plugin/build.gradle.kts @@ -8,6 +8,8 @@ plugins { } gradlePlugin { + website.set("https://github.com/rafaeltonholo/svg-to-compose") + vcsUrl.set("https://github.com/rafaeltonholo/svg-to-compose") plugins { create("svgToCompose") { id = group.toString()