Disable using kapt by default, add JVM overloads for methods for addi…

…ng dependencies and improve documentation Fixes #322 Fixes #325
Kotlin · Aug 29, 2021 · ea59662 · ea59662
1 parent 1d81ec6
commit ea59662
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 11 deletions.
diff --git a/docs/libraries.md b/docs/libraries.md
@@ -68,20 +68,38 @@ plugins {
 }
 ```
 
-This plugin adds dependencies to api and annotations ("scanner") artifacts to your project. You may turn off
-the auto-including of these artifacts by specifying following Gradle properties:
- - `kotlin.jupyter.add.api` to `false`.
- - `kotlin.jupyter.add.scanner` to `false`.
+This plugin adds following dependencies to your project:
+
+| Artifact                         | Gradle option to exclude/include | Enabled by default | Dependency scope     | Method for adding dependency manually    |
+| :------------------------------- | :------------------------------- | :----------------- | :------------------- | :--------------------------------------- |
+| `kotlin-jupyter-api`             | `kotlin.jupyter.add.api`         | yes                | `compileOnly`        | `addApiDependency(version: String?)`     |
+| `kotlin-jupyter-api-annotations` | `kotlin.jupyter.add.scanner`     | no                 | `implementation`     | `addScannerDependency(version: String?)` |
+| `kotlin-jupyter-test-kit`        | `kotlin.jupyter.add.testkit`     | yes                | `testImplementation` | `addTestKitDependency(version: String?)` |
+
+You may turn on / turn off the dependency with its default version (version of the plugin)
+by setting corresponding Gradle option to `true` or `false`.
+If the corresponding option is set to `false` (by default or in your setup), you still
+can add it manually using the method from the table inside `kotlinJupyter` extension like that:
 
-Add these dependencies manually using `kotlinJupyter` extension:
 ```groovy
 kotlinJupyter {
-    addApiDependency("<version>")
-    addScannerDependency("<version>")
+    addApiDependency() // Use default version
+    addApiDependency("0.10.0.1") // Use custom artifact version
 }
 ```
 
-Finally, implement `org.jetbrains.kotlinx.jupyter.api.libraries.LibraryDefinitionProducer` or
+### Adding library integration using annotation processor
+
+If you don't have problems with kapt (i.e. you use JDK version under 16), you can use annotations to
+mark integration classes. 
+
+First, enable `kotlin-jupyter-api-annotations` dependency by adding following line to your `gradle.properties`:
+
+```
+kotlin.jupyter.add.scanner = true
+```
+
+Then, implement `org.jetbrains.kotlinx.jupyter.api.libraries.LibraryDefinitionProducer` or
 `org.jetbrains.kotlinx.jupyter.api.libraries.LibraryDefinition` and mark implementation with
 `JupyterLibrary` annotation:
 
@@ -109,8 +127,9 @@ For a further information see docs for:
  - `org.jetbrains.kotlinx.jupyter.api.libraries.LibraryDefinitionProducer`
  - `org.jetbrains.kotlinx.jupyter.api.libraries.LibraryDefinition`
 
-### Avoiding using annotation processor
+### Adding library integration avoiding use of annotation processor
 You may want not to use annotation processing for implementations detection.
+The reason may be, for example, the problems with kapt.
 Then you may refer your implementations right in your buildscript. Note that
 no checking for existence will be performed in this case.
 

diff --git a/.../src/main/kotlin/org/jetbrains/kotlinx/jupyter/api/plugin/KotlinJupyterPluginExtension.kt b/.../src/main/kotlin/org/jetbrains/kotlinx/jupyter/api/plugin/KotlinJupyterPluginExtension.kt
@@ -11,7 +11,7 @@ class KotlinJupyterPluginExtension(
     private val project: Project
 ) {
     private val enableApiDependency = project.propertyByFlag("kotlin.jupyter.add.api", true)
-    private val enableScannerDependency = project.propertyByFlag("kotlin.jupyter.add.scanner", true)
+    private val enableScannerDependency = project.propertyByFlag("kotlin.jupyter.add.scanner", false)
     private val enableTestKitDependency = project.propertyByFlag("kotlin.jupyter.add.testkit", true)
 
     internal fun addDependenciesIfNeeded() {
@@ -20,10 +20,12 @@ class KotlinJupyterPluginExtension(
         if (enableTestKitDependency.get()) addTestKitDependency()
     }
 
+    @JvmOverloads
     fun addApiDependency(version: String? = null) = with(project) {
         configureDependency("compileOnly", kernelDependency("api", version))
     }
 
+    @JvmOverloads
     fun addScannerDependency(version: String? = null) = with(project) {
         configurations.whenAdded({ it.name == "kapt" }) { kaptConf ->
             val annotationsDependency = kernelDependency("api-annotations", version)
@@ -34,6 +36,7 @@ class KotlinJupyterPluginExtension(
         }
     }
 
+    @JvmOverloads
     fun addTestKitDependency(version: String? = null) = with(project) {
         configureDependency("testImplementation", kernelDependency("test-kit", version))
     }

diff --git a/...lugin/src/test/kotlin/org/jetbrains/kotlinx/jupyter/api/plugin/test/ResourcesTaskTests.kt b/...lugin/src/test/kotlin/org/jetbrains/kotlinx/jupyter/api/plugin/test/ResourcesTaskTests.kt
@@ -37,7 +37,6 @@ class ResourcesTaskTests {
     private fun runResourcesTask(args: Array<String>? = null, type: String = ""): BuildResult {
         val arguments = args?.toMutableList() ?: mutableListOf(
             "-Pkotlin.jupyter.add.api=false",
-            "-Pkotlin.jupyter.add.scanner=false",
             "--stacktrace",
             "--info"
         )