[PEM] Rewrite module documentation

Author: whyoleg

build-logic/src/main/kotlin/ckbuild/docs.kt

@@ -9,3 +9,14 @@ fun DokkaExtension.registerKotlinxIoExternalDocumentation() {
         }
     }
 }
+
+
+fun DokkaExtension.includeCommonDocs() {
+    dokkaSourceSets.configureEach {
+        if (name.endsWith("Main")) {
+            // TODO: dokka requires for `includes` files to be present...
+            //  otherwise we could use `includes.from("src/${name}Docs/module.md")`
+            includes.from("src/commonDocs/module.md")
+        }
+    }
+}

cryptography-serialization/pem/build.gradle.kts

@@ -32,5 +32,6 @@ kover {
 }
 
 dokka {
+    includeCommonDocs()
     registerKotlinxIoExternalDocumentation()
 }

cryptography-serialization/pem/src/commonDocs/module.md

@@ -0,0 +1,18 @@
+# Module cryptography-serialization-pem
+
+Provides PEM encoding/decoding support as defined by [RFC 7468](https://datatracker.ietf.org/doc/html/rfc7468)
+
+The module exposes two main types:
+
+- [PemLabel][PemLabel] – a case-sensitive encapsulation label.
+- [PemDocument][PemDocument] – an immutable value object representing a single PEM document with a label and binary content.
+
+#### [Get complete dependency details at klibs.io](https://klibs.io/package/dev.whyoleg.cryptography/cryptography-serialization-pem)
+
+[PemDocument]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-serialization-pem/dev.whyoleg.cryptography.serialization.pem/-pem-document/index.html
+
+[PemLabel]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-serialization-pem/dev.whyoleg.cryptography.serialization.pem/-pem-label/index.html
+
+# Package dev.whyoleg.cryptography.serialization.pem
+
+Provides PEM encoding/decoding support as defined by [RFC 7468](https://datatracker.ietf.org/doc/html/rfc7468)

docs/serialization/index.md

@@ -2,7 +2,7 @@
 
 At this moment the library provides separate independent modules to work with different cryptography-related serialization formats:
 
-* [PEM](pem.md)
+* [PEM](../api/cryptography-serialization-pem/index.html)
 * [ASN.1/DER](asn1.md)
 
 Support for [JOSE](https://github.com/whyoleg/cryptography-kotlin/issues/16)

docs/serialization/pem.md

@@ -106,26 +106,6 @@ Provides API for working with keys: [encoding][EncodableKey], [decoding][KeyDeco
 
 [KeyGenerator]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.materials.key/-key-generator/index.html
 
-# Module cryptography-serialization-pem
-
-[PEM][PEM]: encoding/decoding of PEM content from/to [String][String] or [ByteArray][ByteArray]
-
-[PEM]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-serialization-pem/dev.whyoleg.cryptography.serialization.pem/-pem-document/index.html
-
-[String]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/
-
-[ByteArray]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-byte-array/
-
-# Package dev.whyoleg.cryptography.serialization.pem
-
-[PEM][PEM]: encoding/decoding of PEM files from/to [String][String] or [ByteArray][ByteArray]
-
-[PEM]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-serialization-pem/dev.whyoleg.cryptography.serialization.pem/-pem-document/index.html
-
-[String]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/
-
-[ByteArray]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-byte-array/
-
 # Module cryptography-serialization-asn1
 
 ASN.1/[DER][DER]: binary serialization of ASN.1/DER content via [kotlinx.serialization][kotlinx.serialization]

dokka/modules.md

@@ -40,8 +40,8 @@ nav:
       - 'OpenSSL3': providers/openssl3.md
   - 'Serialization':
       - serialization/index.md
-      - 'PEM': serialization/pem.md
       - 'ASN.1/DER': serialization/asn1.md
+  - 'PEM': api/cryptography-serialization-pem/index.html
   - 'API': api/index.html
 
 theme: