From 28137e44e150944f5b7758f008dd1d441585aea7 Mon Sep 17 00:00:00 2001 From: Alexander Nozik Date: Fri, 25 Sep 2020 10:13:38 +0300 Subject: [PATCH] Readme auto-generation via plugin --- README.md | 29 +++++-- build.gradle.kts | 81 +------------------ docs/templates/ARTIFACT-TEMPLATE.md | 29 +++++++ .../README-TEMPLATE.md} | 10 +-- kmath-core/build.gradle.kts | 39 ++++++++- .../{README-STUB.md => README-TEMPLATE.md} | 8 +- kmath-core/docs/kscience-module.json | 36 --------- settings.gradle.kts | 23 +++--- 8 files changed, 112 insertions(+), 143 deletions(-) create mode 100644 docs/templates/ARTIFACT-TEMPLATE.md rename docs/{README-STUB.md => templates/README-TEMPLATE.md} (85%) rename kmath-core/docs/{README-STUB.md => README-TEMPLATE.md} (77%) delete mode 100644 kmath-core/docs/kscience-module.json diff --git a/README.md b/README.md index 44363b27a..4d89337b5 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,12 @@ can be used for a wide variety of purposes from high performance calculations to ## Modules +### [examples](examples) + +### [kmath-ast](kmath-ast) + +### [kmath-commons](kmath-commons) + ### [kmath-core](kmath-core) - [algebras](kmath-core/src/commonMain/kotlin/kscience/kmath/operations/Algebra.kt) : Algebraic structures: contexts and elements - [nd](kmath-core/src/commonMain/kotlin/kscience/kmath/structures/NDStructure.kt) : Many-dimensional structures @@ -77,17 +83,24 @@ can be used for a wide variety of purposes from high performance calculations to - [autodif](kmath-core/src/commonMain/kotlin/kscience/kmath/misc/AutoDiff.kt) : Automatic differentiation ### [kmath-coroutines](kmath-coroutines) -### [kmath-viktor](kmath-viktor) -### [kmath-prob](kmath-prob) -### [kmath-ast](kmath-ast) -### [kmath-commons](kmath-commons) -### [kmath-memory](kmath-memory) -### [kmath-for-real](kmath-for-real) -### [kmath-functions](kmath-functions) + ### [kmath-dimensions](kmath-dimensions) -### [kmath-histograms](kmath-histograms) + +### [kmath-for-real](kmath-for-real) + +### [kmath-functions](kmath-functions) + ### [kmath-geometry](kmath-geometry) +### [kmath-histograms](kmath-histograms) + +### [kmath-memory](kmath-memory) + +### [kmath-prob](kmath-prob) + +### [kmath-viktor](kmath-viktor) + + ## Multi-platform support diff --git a/build.gradle.kts b/build.gradle.kts index ed3317bf8..81e0cb973 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,6 +1,6 @@ plugins { - id("ru.mipt.npm.base") - id("org.jetbrains.changelog") version "0.4.0" + //id("ru.mipt.npm.publish") apply false + id("ru.mipt.npm.project") } val kmathVersion by extra("0.2.0-dev-1") @@ -22,79 +22,6 @@ subprojects { if (name.startsWith("kmath")) apply() } -/** - * TODO move to base plugin - */ -val generateReadme by tasks.creating { - group = "documentation" - - fun List>.generateFeatureString(pathPrefix: String): String = buildString { - this@generateFeatureString.forEach { feature -> - val id by feature - val description by feature - val ref by feature - appendln(" - [$id]($pathPrefix$ref) : $description") - } - } - - doLast { - val reader = groovy.json.JsonSlurper() - val projects = HashMap>() - - project.subprojects { - var properties: Map = mapOf( - "name" to this.name, - "group" to this.group, - "version" to this.version - ) - - val projectProperties = this.file("docs/kscience-module.json") - - @Suppress("UNCHECKED_CAST") - if (projectProperties.exists()) { - val customProperties: Map = - (reader.parse(projectProperties) as? Map ?: emptyMap()).withDefault { null } - val features: List>? by customProperties - val featureString = features?.generateFeatureString("") - properties = customProperties + properties + ("featuresString" to featureString) - } - - projects[name] = properties.withDefault { null } - - val readmeStub = this.file("docs/README-STUB.md") - if (readmeStub.exists()) { - val readmeFile = this.file("README.md") - readmeFile.writeText( - groovy.text.SimpleTemplateEngine().createTemplate(readmeStub).make(properties).toString() - ) - } - } - - val rootReadmeStub = project.file("docs/README-STUB.md") - - val modulesString = buildString { - projects.filter { it.key.startsWith("kmath") }.forEach { (name, properties) -> - appendln("### [$name]($name)") - val features: List>? by properties - if (features != null) { - appendln(features!!.generateFeatureString("$name/")) - } - } - } - - val rootReadmeProperties: Map = mapOf( - "name" to project.name, - "group" to project.group, - "version" to project.version, - "modulesString" to modulesString - ) - - if (rootReadmeStub.exists()) { - val readmeFile = project.file("README.md") - readmeFile.writeText( - groovy.text.SimpleTemplateEngine().createTemplate(rootReadmeStub).make(rootReadmeProperties).toString() - ) - } - - } +readme{ + readmeTemplate = file("docs/template/README-TEMPLATE.md") } \ No newline at end of file diff --git a/docs/templates/ARTIFACT-TEMPLATE.md b/docs/templates/ARTIFACT-TEMPLATE.md new file mode 100644 index 000000000..1b354e022 --- /dev/null +++ b/docs/templates/ARTIFACT-TEMPLATE.md @@ -0,0 +1,29 @@ +> #### Artifact: +> This module artifact: `${group}:${name}:${version}`. +> +> **Gradle:** +> +> ```gradle +> repositories { +> maven { url 'https://dl.bintray.com/mipt-npm/kscience' } +> maven { url 'https://dl.bintray.com/mipt-npm/dev' } +> maven { url https://dl.bintray.com/hotkeytlt/maven' } +> } +> +> dependencies { +> implementation '${group}:${name}:${version}' +> } +> ``` +> **Gradle Kotlin DSL:** +> +> ```kotlin +> repositories { +> maven("https://dl.bintray.com/mipt-npm/kscience") +> maven("https://dl.bintray.com/mipt-npm/dev") +> maven("https://dl.bintray.com/hotkeytlt/maven") +> } +> +> dependencies { +> implementation("${group}:${name}:${version}") +> } +> ``` \ No newline at end of file diff --git a/docs/README-STUB.md b/docs/templates/README-TEMPLATE.md similarity index 85% rename from docs/README-STUB.md rename to docs/templates/README-TEMPLATE.md index 1c6a1f6e0..f451adb24 100644 --- a/docs/README-STUB.md +++ b/docs/templates/README-TEMPLATE.md @@ -9,9 +9,9 @@ Bintray-dev: [ ![Download](https://api.bintray.com/packages/mipt-npm/dev/kmat # KMath Could be pronounced as `key-math`. -The Kotlin MATHematics library is intended as a Kotlin-based analog to Python's `numpy` library. In contrast to `numpy` and `scipy` it is modular and has a lightweight core. +The Kotlin MATHematics library was initially intended as a Kotlin-based analog to Python's `numpy` library. Later we found that kotlin is much more flexible language and allows superior architecture designs. In contrast to `numpy` and `scipy` it is modular and has a lightweight core. The `numpy`-like experience could be achieved with [kmath-for-real](/kmath-for-real) extension module. -## Publications +## Publications and talks * [A conceptual article about context-oriented design](https://proandroiddev.com/an-introduction-context-oriented-programming-in-kotlin-2e79d316b0a2) * [Another article about context-oriented design](https://proandroiddev.com/diving-deeper-into-context-oriented-programming-in-kotlin-3ecb4ec38814) * [ACAT 2019 conference paper](https://aip.scitation.org/doi/abs/10.1063/1.5130103) @@ -29,7 +29,7 @@ The Kotlin MATHematics library is intended as a Kotlin-based analog to Python's ## Features -Actual feature list is [here](docs/features.md) +Actual feature list is [here](/docs/features.md) * **Algebra** * Algebraic structures like rings, spaces and field (**TODO** add example to wiki) @@ -68,11 +68,11 @@ can be used for a wide variety of purposes from high performance calculations to ## Modules -$modulesString +$modules ## Multi-platform support -KMath is developed as a multi-platform library, which means that most of interfaces are declared in the [common module](kmath-core/src/commonMain). Implementation is also done in the common module wherever possible. In some cases, features are delegated to platform-specific implementations even if they could be done in the common module for performance reasons. Currently, the JVM is the main focus of development, however Kotlin/Native and Kotlin/JS contributions are also welcome. +KMath is developed as a multi-platform library, which means that most of the interfaces are declared in the [common module](/kmath-core/src/commonMain). Implementation is also done in the common module wherever possible. In some cases, features are delegated to platform-specific implementations even if they could be done in the common module for performance reasons. Currently, the JVM is the main focus of development, however Kotlin/Native and Kotlin/JS contributions are also welcome. ## Performance diff --git a/kmath-core/build.gradle.kts b/kmath-core/build.gradle.kts index e315e1640..31a16e20b 100644 --- a/kmath-core/build.gradle.kts +++ b/kmath-core/build.gradle.kts @@ -1,7 +1,44 @@ -plugins { id("ru.mipt.npm.mpp") } +plugins { + id("ru.mipt.npm.mpp") +} kotlin.sourceSets.commonMain { dependencies { api(project(":kmath-memory")) } } + +readme { + description = "Core classes, algebra definitions, basic linear algebra" + maturity = ru.mipt.npm.gradle.Maturity.DEVELOPMENT + feature( + id = "algebras", + description = "Algebraic structures: contexts and elements", + ref = "src/commonMain/kotlin/kscience/kmath/operations/Algebra.kt" + ) + feature( + id = "nd", + description = "Many-dimensional structures", + ref = "src/commonMain/kotlin/kscience/kmath/structures/NDStructure.kt" + ) + feature( + id = "buffers", + description = "One-dimensional structure", + ref = "src/commonMain/kotlin/kscience/kmath/structures/Buffers.kt" + ) + feature( + id = "expressions", + description = "Functional Expressions", + ref = "src/commonMain/kotlin/kscience/kmath/expressions" + ) + feature( + id = "domains", + description = "Domains", + ref = "src/commonMain/kotlin/kscience/kmath/domains" + ) + feature( + id = "autodif", + description = "Automatic differentiation", + ref = "src/commonMain/kotlin/kscience/kmath/misc/AutoDiff.kt" + ) +} \ No newline at end of file diff --git a/kmath-core/docs/README-STUB.md b/kmath-core/docs/README-TEMPLATE.md similarity index 77% rename from kmath-core/docs/README-STUB.md rename to kmath-core/docs/README-TEMPLATE.md index c2e8f661f..183f300ac 100644 --- a/kmath-core/docs/README-STUB.md +++ b/kmath-core/docs/README-TEMPLATE.md @@ -1,10 +1,10 @@ # The Core Module (`kmath-core`) The core features of KMath: -$featuresString +$features > #### Artifact: -> This module artifact: `$group:kmath-core:$version`. +> This module artifact: `${group}:${name}:${version}`. > > **Gradle:** > @@ -16,7 +16,7 @@ $featuresString > } > > dependencies { -> implementation '$group:kmath-core:$version' +> implementation '${group}:${name}:${version}' > } > ``` > **Gradle Kotlin DSL:** @@ -29,6 +29,6 @@ $featuresString > } > > dependencies { -> implementation("$group:kmath-core:$version") +> implementation("${group}:${name}:${version}") > } > ``` diff --git a/kmath-core/docs/kscience-module.json b/kmath-core/docs/kscience-module.json deleted file mode 100644 index c7ac4f082..000000000 --- a/kmath-core/docs/kscience-module.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "description": "Core classes, algebra definitions, basic linear algebra", - "maturity": "development", - "features": [ - { - "id": "algebras", - "description": "Algebraic structures: contexts and elements", - "ref": "src/commonMain/kotlin/kscience/kmath/operations/Algebra.kt" - }, - { - "id": "nd", - "description": "Many-dimensional structures", - "ref": "src/commonMain/kotlin/kscience/kmath/structures/NDStructure.kt" - }, - { - "id": "buffers", - "description": "One-dimensional structure", - "ref": "src/commonMain/kotlin/kscience/kmath/structures/Buffers.kt" - }, - { - "id": "expressions", - "description": "Functional Expressions", - "ref": "src/commonMain/kotlin/kscience/kmath/expressions" - }, - { - "id": "domains", - "description": "Domains", - "ref": "src/commonMain/kotlin/kscience/kmath/domains" - }, - { - "id": "autodif", - "description": "Automatic differentiation", - "ref": "src/commonMain/kotlin/kscience/kmath/misc/AutoDiff.kt" - } - ] -} \ No newline at end of file diff --git a/settings.gradle.kts b/settings.gradle.kts index fe0ee6c5d..ad9014e56 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -1,15 +1,4 @@ pluginManagement { - val toolsVersion = "0.6.0" - - plugins { - id("kotlinx.benchmark") version "0.2.0-dev-20" - id("ru.mipt.npm.base") version toolsVersion - id("ru.mipt.npm.mpp") version toolsVersion - id("ru.mipt.npm.jvm") version toolsVersion - id("ru.mipt.npm.publish") version toolsVersion - kotlin("plugin.allopen") - } - repositories { mavenLocal() jcenter() @@ -20,6 +9,17 @@ pluginManagement { maven("https://dl.bintray.com/kotlin/kotlinx") maven("https://dl.bintray.com/kotlin/kotlin-dev/") } + + val toolsVersion = "0.6.1" + + plugins { + id("kotlinx.benchmark") version "0.2.0-dev-20" + id("ru.mipt.npm.project") version toolsVersion + id("ru.mipt.npm.mpp") version toolsVersion + id("ru.mipt.npm.jvm") version toolsVersion + id("ru.mipt.npm.publish") version toolsVersion + kotlin("plugin.allopen") + } } rootProject.name = "kmath" @@ -33,7 +33,6 @@ include( ":kmath-commons", ":kmath-viktor", ":kmath-prob", -// ":kmath-io", ":kmath-dimensions", ":kmath-for-real", ":kmath-geometry",