commit 5459c10508d8d354098e6422499d0e8b9f453d70
author Roman Elizarov <elizarov@gmail.com> Tue Aug 11 12:27:36 2020 +0300
committer GitHub <noreply@github.com> Tue Aug 11 12:27:36 2020 +0300
tree 05949893d311f8ba6bfacdb08a8570f57357a8b4
parent 65fdbc7d8ac24c96110a6b1230f7a361e5e145bc

Docs: Kotlin Serialization Guide (#933)


Documentation from the docs folder is incorporated into a common story that spans six chapters and proceeds from the basic serialization to the experimental alternative and custom formats. The example files are automatically generated from the text with the Knit tool (guide/example folder) and are verified with the automatically generated tests (guide/test folder).

The entry point to the new is docs/serialization-guide.md that contains the overall table of contents and links to the specific chapters.

The old docs that are being incorporated:
* cbor_byte_string.md -> formats.md
* custom_serializers.md -> serializers.md
* examples.md -> basic-serialization.md
* json_transformations.md -> json.md
* old12.md (removed completely as obsolete)
* runtime_usage.md -> various chapters

Additional changes include:
* Top-level README.md file is cleaned up from legacy information and also contains a modern knitted example.
* More consistent error messages in various exceptions.
* Minor corrections to KDocs and APIs.
* Better style.css for the documentation that is generated by Dokka.
* Improved update_docs.sh to put temporary files inside the build folder.

Co-authored-by: Vsevolod Tolstopyatov <qwwdfsad@gmail.com>

build.gradle

diff --git a/build.gradle b/build.gradle
index d90e6a1..947a1a3 100644
--- a/build.gradle
+++ b/build.gradle
@@ -19,8 +19,8 @@
 
     ext.experimentalsInTestEnabled = ["-progressive", "-Xuse-experimental=kotlin.Experimental",
                                       "-Xuse-experimental=kotlin.ExperimentalMultiplatform",
-                                      "-Xuse-experimental=kotlinx.serialization.UnsafeSerializationApi",
-                                      "-Xuse-experimental=kotlinx.serialization.InternalSerializationApi"
+                                      "-Xuse-experimental=kotlinx.serialization.InternalSerializationApi",
+                                      "-Xuse-experimental=kotlin.ExperimentalUnsignedTypes"
     ]
 
     /*
@@ -71,6 +71,7 @@
         classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
         classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
         classpath "org.jetbrains.kotlinx:binary-compatibility-validator:$validator_version"
+        classpath "org.jetbrains.kotlinx:kotlinx-knit:$knit_version"
 
         classpath 'com.google.protobuf:protobuf-gradle-plugin:0.8.8'
 
@@ -86,9 +87,19 @@
 apply plugin: 'binary-compatibility-validator'
 
 apiValidation {
-    ignoredProjects += ["benchmark", "kotlinx-serialization"]
+    ignoredProjects += ["benchmark", "guide", "kotlinx-serialization"]
 }
 
+apply plugin: 'base'
+apply plugin: 'kotlinx-knit'
+
+knit {
+    siteRoot = "https://kotlin.github.io/kotlinx.serialization"
+}
+
+// Build API docs for all modules with dokka before running Knit
+knitPrepare.dependsOn "dokka"
+
 allprojects {
     group 'org.jetbrains.kotlinx'
 
@@ -144,8 +155,10 @@
 
     apply from: rootProject.file('gradle/teamcity.gradle')
     // Configure publishing for some artifacts
-    if (project.name.contains("benchmark")) return
-    apply from: rootProject.file('gradle/publishing.gradle')
+    if (project.name != "benchmark" && project.name != "guide") {
+        apply from: rootProject.file('gradle/publishing.gradle')
+    }
+
 }
 
 apply from: rootProject.file('gradle/compilerVersion.gradle')