Merge branch 'documentation'

README.md

@@ -0,0 +1 @@
+<img alt="KODEIN-LOG" src="https://raw.githubusercontent.com/Kodein-Framework/Kodein-Log/master/doc/modules/ROOT/images/kodein-log-logo.svg" width="700">

doc/antora.yml

@@ -0,0 +1,12 @@
+name: kodein-log
+title: Kodein-Log
+version: '0.10'
+display_version: '0.10.1'
+nav:
+  - modules/ROOT/nav.adoc
+  - modules/core/nav.adoc
+asciidoc:
+  attributes:
+    version: '0.10.1'
+    kotlin: '1.4.31'
+    jdk: '1.8'

doc/modules/ROOT/nav.adoc

@@ -0,0 +1,2 @@
+* xref:index.adoc[Introduction]
+* xref:getting-started.adoc[Quick start guide]

doc/modules/ROOT/pages/getting-started.adoc

@@ -0,0 +1,79 @@
+
+= Getting started with Kodein-Log
+
+NOTE: This guide assumes a JVM target.
+      Kodein-Log works exactly the same on all targets that are supported by Kotlin (JVM, Android, JS, Native).
+
+== Install
+
+In your `build.gradle.kts` file, add the Maven Central repository:
+
+[source,kotlin]
+----
+repositories {
+  mavenCentral()
+}
+----
+
+Then add the dependency:
+
+[source,groovy,subs="attributes"]
+----
+dependencies {
+    implementation 'org.kodein.log:kodein-log:{version}'
+}
+----
+
+More detailed installation guide xref:core:install.adoc[here].
+
+== Create and use a `Logger`
+
+Before being able to log anything, you need to create a `LoggerFactory`,
+to define the format of your logs and on which frontend they should be sent.
+
+. create a `LoggerFactory`
++
+[source,kotlin]
+----
+val loggerFactory = LoggerFactory.default // <1>
+----
+<1> Initialize a `LoggerFactory` with the xref:core:usage.adoc#default-frontends[default] output format.
+
+. create a `Logger`
++
+[source,kotlin]
+----
+class MyController {
+    private val logger = LoggerFactory.default.newLogger<MyController>() // <1>
+}
+----
+<1> Initialize a `Logger` from a given `LoggerFactory`.
++
+[NOTE]
+====
+
+Thanks to the awesome Kotlin type system we can even go further,
+without explicitly naming the Tag used for logging:
+
+[source,kotlin]
+----
+class MyController(private val loggerFactory: LoggerFactory) {
+    private val logger = newLogger(loggerFactory) // <1>
+}
+----
+<1> Initialize a `Logger` from a given `LoggerFactory`, implicitly tagged with `MyController`.
+====
+
+. Use the logger
++
+[source,kotlin]
+----
+logger.info { "Well done..." }
+logger.warning { "...you have completed the Getting Started guide." }
+----
++
+NOTE: Logging levels available: `debug` / `info` / `warning` / `error`.
+
+More detailed on `Logger` xref:core:usage.adoc[initialization and usage].
+
+If you want to know more about frontend implementation you can read xref:core:advanced.adoc[Working with custom frontends].

doc/modules/ROOT/pages/index.adoc

@@ -0,0 +1,42 @@
+image::kodein-log-logo.svg[KODEIN-LOG, 700]
+
+[.lead]
+*_Kodein-Log_* is a lightweight Kotlin/Multiplatform logging library with a simple API, that works on JVM, Android, JavaScript, iOS, as well as for all Kotlin/Native targets.
+
+*_Kodein-Log_* allows you to:
+
+- easily setup logging in a Kotlin/Multiplatform
+- simply log what you need on different level
+- avoid carrying about platform specific frontends' implementations
+
+*_Kodein-Log_* is a good choice because:
+
+- it integrates nicely with all the Kotlin/Multiplatform targets
+- it is small and simple to grasp with an easy and understandable API
+
+== Example
+
+[source, kotlin]
+.simple example
+----
+val loggerFactory = LoggerFactory(defaultLogFrontend)
+val logger = newLogger(loggerFactory)
+
+logger.info { "Welcome to ..." }
+logger.warning { "... the Kodein-Log documentation!" }
+----
+
+== Support
+
+- Drop by the https://kotlinlang.slack.com/messages/kodein/[Kodein Slack channel]
+- https://stackoverflow.com/questions/tagged/kodein[Stackoverflow] with the tag #kodein
+
+== Contribute
+
+Contributions are very welcome and greatly appreciated! The great majority of pull requests are eventually merged.
+
+To contribute, simply fork https://github.com/Kodein-Framework/Kodein-Log[the project on Github], fix whatever is iching you, and submit a pull request!
+
+I am sure that this documentation contains typos, inaccuracies and languages error (English is not our mother tongue).
+If you feel like enhancing this document, you can propose a pull request that modifies https://github.com/Kodein-Framework/Kodein-Log/tree/master/doc[the documentation documents].
+(Documentation is auto-generated from those).

doc/modules/core/nav.adoc

@@ -0,0 +1,12 @@
+* xref:install.adoc[Install]
+** xref:install.adoc#install-kmp[Kotlin/Multiplatform]
+** xref:install.adoc#install-jvm[JVM & Android only]
+** xref:install.adoc#install-js[JavaScript]
+* xref:usage.adoc#logger[Create and use a `Logger`]
+** xref:usage.adoc#tags[Tags]
+** xref:usage.adoc#default-frontends[Default frontends]
+** xref:usage.adoc#levels[Logging levels]
+* xref:usage.adoc#logger-factory[Share the logger configuration]
+* xref:usage.adoc#logmapper[Transform the outputs]
+* xref:usage.adoc#logfilter[Filter the outputs]
+* xref:advanced.adoc#custom-frontends[Working with custom frontends]

doc/modules/core/pages/advanced.adoc

@@ -0,0 +1,41 @@
+= Advanced
+
+[[custom-frontends]]
+== Working with custom frontends
+
+*_Kodein-Log_* is a facade for multiplatform developers that need an easy way to log without worrying about platform specific implementation. For that we provide xref:usage.adoc#default-frontends[[default frontends]] that are default output capacities, for each possible target of Kotlin/Multiplatform.
+
+However, we can think of a lot of use cases that might not covered by default frontends, ike saving the logs into a file, sending the logs to an upstream system, etc.
+
+If you want to use a custom implementation to handle your logs, you can create your own by using the interface `LogFrontend`.
+
+[source,kotlin]
+.`logFrontend`
+----
+public fun interface LogFrontend {
+    public fun getReceiverFor(tag: Logger.Tag): LogReceiver // <1>
+}
+----
+<1> You only have to override `getReceiverFor`.
+
+The `getReceiverFor` function will define what we should do of every logged entry. The rest depends on your use case. Here is an example of a frontend that will stack every log into a list:
+
+[source,kotlin]
+.custom frontend
+----
+class MemoryFrontend : LogFrontend { // <1>
+    val entries: MutableList<Triple<Logger.Tag, Logger.Entry, String?>> = ArrayList() // <2>
+
+    override fun getReceiverFor(tag: Logger.Tag): LogReceiver = // <3>
+        LogReceiver { entry, message -> // <4>
+            entries += Triple(tag, entry, message) // <5>
+        }
+}
+----
+<1> implement `LogFrontend`
+<2> create a mutable list that will carry the logs
+<3> override `getReceiveFor`
+<4> create a `LogReceiver` ...
+<5> ... that populate the `entries` with each log received
+
+NOTE: We could use this example to periodically send our stack to an upstream server.

doc/modules/core/pages/install.adoc

@@ -0,0 +1,90 @@
+[[install]]
+= Install
+
+IMPORTANT: *_Kodein-Log_* uses the new gradle native dependency model.
+            Thus, we highly recommend to use Gradle 6 or higher.
+
+[[install-kmp]]
+== Kotlin/Multiplatform
+
+NOTE: Kodein-Log supports the following targets: +
+jvm, iosArm32, iosArm64, iosX64, JS, tvosarm64, tvosx64, watchosarm32, watchosarm64, watchosx86, linuxArm32Hfp, linuxMips32, linuxMipsel32, linuxX64, macosX64, mingwX64.
+
+In your `build.gradle.kts` file, add the Maven Central repository:
+
+[source,kotlin]
+----
+repositories {
+    mavenCentral()
+}
+----
+
+Then add the dependency:
+
+[source,kotlin,subs="attributes"]
+----
+kotlin {
+    sourceSets {
+        commonMain {
+            dependencies {
+                implementation("org.kodein.log:kodein-log:{version}")
+            }
+        }
+    }
+}
+----
+
+[TIP]
+====
+If you are *NOT* using *Gradle 6+*, you should declare the use of the Gradle Metadata experimental feature
+
+[subs="attributes"]
+.settings.gradle.kts
+----
+enableFeaturePreview("GRADLE_METADATA")
+----
+====
+
+[[install-jvm]]
+== JVM & Android
+
+On the JVM, *_Kodein-Log_* is compatible with both standard JVM and Android environments, with the same configuration.
+
+First, add the Maven Central repository:
+
+[source,kotlin]
+----
+repositories {
+    mavenCentral()
+}
+----
+
+Then add the dependency:
+
+[source,kotlin,subs="attributes"]
+----
+dependencies {
+    implementation("org.kodein.log:kodein-log-jvm:{version}")
+}
+----
+
+[[install-js]]
+== JavaScript
+
+Add the Maven Central repository:
+
+[source,kotlin]
+----
+repositories {
+    mavenCentral()
+}
+----
+
+Then add the dependency:
+
+[source,kotlin,subs="attributes"]
+----
+dependencies {
+    implementation("org.kodein.log:kodein-log-js:{version}")
+}
+----