From 2c2c21bb5af010bdb7f711e49a109d5fd3eb7343 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 3 Oct 2024 20:23:03 +0200 Subject: [PATCH 01/10] build(website): Remove the hardcoded table of contents --- docs/website/mkdocs.yml | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 1f4a20a..d6817aa 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -92,18 +92,4 @@ nav: - reference.md # !!! EMBEDDED DOKKA START, DO NOT COMMIT !!! # - - Reference: - - example-core: - - api/example-core/index.md - - opensavvy.dokka.material.mkdocs.example: - - api/example-core/opensavvy.dokka.material.mkdocs.example/index.md - - Example: - - api/example-core/opensavvy.dokka.material.mkdocs.example/-example/index.md - - api/example-core/opensavvy.dokka.material.mkdocs.example/-example/-example.md - - api/example-core/opensavvy.dokka.material.mkdocs.example/-example/foo.md - - example-app: - - api/example-app/index.md - - opensavvy.dokka.material.mkdocs.example: - - api/example-app/opensavvy.dokka.material.mkdocs.example/index.md - - api/example-app/opensavvy.dokka.material.mkdocs.example/main.md # !!! EMBEDDED DOKKA END, DO NOT COMMIT !!! # -- 2.51.2 From 2099b945bf79870e4136e3f7559828ea8739c21c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 3 Oct 2024 20:44:43 +0200 Subject: [PATCH 02/10] fix(renderer): Fix module pages being broken when they contain spaces --- docs/example/example-app/build.gradle.kts | 4 ++++ renderer/src/main/kotlin/location/MarkdownLocationProvider.kt | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/example/example-app/build.gradle.kts b/docs/example/example-app/build.gradle.kts index 10dae69..f13f9f5 100644 --- a/docs/example/example-app/build.gradle.kts +++ b/docs/example/example-app/build.gradle.kts @@ -14,3 +14,7 @@ kotlin { implementation(projects.example.exampleCore) } } + +dokkatoo { + moduleName.set("Example app") +} diff --git a/renderer/src/main/kotlin/location/MarkdownLocationProvider.kt b/renderer/src/main/kotlin/location/MarkdownLocationProvider.kt index 1c6189d..1cad637 100644 --- a/renderer/src/main/kotlin/location/MarkdownLocationProvider.kt +++ b/renderer/src/main/kotlin/location/MarkdownLocationProvider.kt @@ -28,7 +28,7 @@ class MarkdownLocationProvider( val default = super.pathTo(node, context) return when (node) { - is ModulePageNode -> "${dokkaContext.configuration.moduleName}/$default" + is ModulePageNode -> "${dokkaContext.configuration.moduleName.map { if (it.isUpperCase()) "-${it.lowercase()}" else it }.joinToString("")}/$default" else -> { return default error( -- 2.51.2 From b3211639b0683dad1264c89c0df2050ecd463326 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 3 Oct 2024 20:53:53 +0200 Subject: [PATCH 03/10] fix: Add a module header description, hide its 'includes' folder --- docs/example/example-core/README.md | 21 +++++++++++++++++++ docs/example/example-core/build.gradle.kts | 8 +++++++ .../src/main/kotlin/DokkatooMkDocsPlugin.kt | 2 ++ 3 files changed, 31 insertions(+) create mode 100644 docs/example/example-core/README.md diff --git a/docs/example/example-core/README.md b/docs/example/example-core/README.md new file mode 100644 index 0000000..86aa5b8 --- /dev/null +++ b/docs/example/example-core/README.md @@ -0,0 +1,21 @@ +# Module Library module + +This is a demonstration of how to use the Dokka format. + +This text is written in a markdown file that is included in the library module. Dokka uses it to generate the module and package headers. + +In this file, you can include code: +```kotlin +println("Hello world!") +``` +as well as other Markdown features, like quotes: + +> This is a quote. + +## This is a subheader + +Module pages can have subheaders to describe multiple sections of content. + +# Package opensavvy.dokka.material.mkdocs.example + +This is the description of a package. diff --git a/docs/example/example-core/build.gradle.kts b/docs/example/example-core/build.gradle.kts index 5c60c34..bcad4db 100644 --- a/docs/example/example-core/build.gradle.kts +++ b/docs/example/example-core/build.gradle.kts @@ -10,3 +10,11 @@ kotlin { nodejs() } } + +dokkatoo { + moduleName.set("Library module") + + dokkatooSourceSets.configureEach { + includes.from("README.md") + } +} diff --git a/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt b/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt index 3ec4e23..907a1e5 100644 --- a/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt +++ b/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt @@ -29,6 +29,8 @@ abstract class DokkatooMkDocsPlugin : DokkatooFormatPlugin(formatName = "mkdocs" path = path.removePrefix("module/") } + exclude("includes/*") + includeEmptyDirs = true duplicatesStrategy = DuplicatesStrategy.WARN // TODO make each module generate files in its own directory, afterwards remove this } -- 2.51.2 From 0e4f3bcccb6066200c536b4ce8f4b373b050acbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 3 Oct 2024 21:31:15 +0200 Subject: [PATCH 04/10] feat(renderer): List packages in the module header --- docs/example/example-core/README.md | 3 ++ .../main/kotlin/renderer/MkDocsRenderer2.kt | 29 ++++++++++++++++++- 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/example/example-core/README.md b/docs/example/example-core/README.md index 86aa5b8..4dbc7d5 100644 --- a/docs/example/example-core/README.md +++ b/docs/example/example-core/README.md @@ -19,3 +19,6 @@ Module pages can have subheaders to describe multiple sections of content. # Package opensavvy.dokka.material.mkdocs.example This is the description of a package. + +The description may be arbitrary long, but only the first paragraph is displayed in the module page. +However, it is contained in its entirety in the package page. diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt index bbd0970..4da8370 100644 --- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt +++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt @@ -5,6 +5,7 @@ import opensavvy.dokka.material.mkdocs.MaterialForMkDocsPlugin import opensavvy.dokka.material.mkdocs.ResolveLinkGfmCommand import org.jetbrains.dokka.DokkaException import org.jetbrains.dokka.base.renderers.DefaultRenderer +import org.jetbrains.dokka.links.PointingToDeclaration import org.jetbrains.dokka.model.DisplaySourceSet import org.jetbrains.dokka.pages.* import org.jetbrains.dokka.plugability.DokkaContext @@ -76,6 +77,25 @@ open class MkDocsRenderer2( override fun StringBuilder.buildTable(node: ContentTable, pageContext: ContentPage, sourceSetRestriction: Set?) { buildComment { "TABLE NODE $node" } + + when (node.dci.kind) { + ContentKind.Packages -> { + for (pkg in node.children) { + for (child in pkg.children) { + when (child) { + is ContentDRILink -> { + appendLine("

") + buildDRILink(child, pageContext, sourceSetRestriction) + appendLine("

") + } + else -> { + buildContentNode(child, pageContext, sourceSetRestriction) + } + } + } + } + } + } } override fun StringBuilder.buildResource(node: ContentEmbeddedResource, pageContext: ContentPage) { @@ -124,7 +144,7 @@ open class MkDocsRenderer2( pageContext: ContentPage, sourceSetRestriction: Set?, ) { - val location = locationProvider.resolve(node.address, node.sourceSets, pageContext) + var location = locationProvider.resolve(node.address, node.sourceSets, pageContext) ?.removeSuffix(".md") ?.plus(".html") if (location == null) { @@ -138,6 +158,13 @@ open class MkDocsRenderer2( buildText(node.children, pageContext, sourceSetRestriction) } } else { + if (node.address.packageName != null && node.address.classNames == null && node.address.callable == null && node.address.target == PointingToDeclaration) { + // We're reading a package definition. + // For some reason, Dokka generates a full path for them, + + location = location.replaceBefore("/", "").removePrefix("/") + } + buildLink(location) { buildText(node.children, pageContext, sourceSetRestriction) } -- 2.51.2 From c5e3056e1d9c4a5755b1ac500456c86e27e94608 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 3 Oct 2024 21:38:49 +0200 Subject: [PATCH 05/10] fix(renderer): Fix tables of content --- renderer/src/main/kotlin/renderer/Decoration.kt | 6 ++++++ renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt | 12 ++++++------ 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/renderer/src/main/kotlin/renderer/Decoration.kt b/renderer/src/main/kotlin/renderer/Decoration.kt index d3e9ef1..cb2c28d 100644 --- a/renderer/src/main/kotlin/renderer/Decoration.kt +++ b/renderer/src/main/kotlin/renderer/Decoration.kt @@ -25,6 +25,12 @@ fun interface Decoration { append("") } + fun ofPrefix(prefix: String) = + Decoration { content -> + append(prefix) + content() + } + val NoOp = Decoration {content -> content() } diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt index 4da8370..6b5b4f9 100644 --- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt +++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt @@ -179,12 +179,12 @@ open class MkDocsRenderer2( override fun StringBuilder.buildHeader(level: Int, node: ContentHeader, content: StringBuilder.() -> Unit) { val decorator = when (level) { - 1 -> Decoration.ofElement("h1") - 2 -> Decoration.ofElement("h2") - 3 -> Decoration.ofElement("h3") - 4 -> Decoration.ofElement("h4") - 5 -> Decoration.ofElement("h5") - else -> Decoration.ofElement("h6") + 1 -> Decoration.ofPrefix("# ") + 2 -> Decoration.ofPrefix("## ") + 3 -> Decoration.ofPrefix("### ") + 4 -> Decoration.ofPrefix("#### ") + 5 -> Decoration.ofPrefix("##### ") + else -> Decoration.ofPrefix("###### ") } decorator.wrapIn(this) { -- 2.51.2 From 50968764fc99bf4d6bea3dd55bf84fadc38ac331 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 3 Oct 2024 21:43:47 +0200 Subject: [PATCH 06/10] fix(renderer): Fix tables of content for the package list --- renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt index 6b5b4f9..7fbd487 100644 --- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt +++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt @@ -84,9 +84,9 @@ open class MkDocsRenderer2( for (child in pkg.children) { when (child) { is ContentDRILink -> { - appendLine("

") - buildDRILink(child, pageContext, sourceSetRestriction) - appendLine("

") + buildHeader(3, ContentHeader(listOf(child), 3, child.dci, child.sourceSets, child.style, child.extra)) { + buildDRILink(child, pageContext, sourceSetRestriction) + } } else -> { buildContentNode(child, pageContext, sourceSetRestriction) -- 2.51.2 From 38a0f3ea6a478750a6772e78b66218ccc05d2af8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 3 Oct 2024 21:51:56 +0200 Subject: [PATCH 07/10] feat(renderer): Display the classes and methods in the package view --- docs/example/example-core/src/commonMain/kotlin/Example.kt | 7 +++++++ renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/example/example-core/src/commonMain/kotlin/Example.kt b/docs/example/example-core/src/commonMain/kotlin/Example.kt index 5dab3bb..6175a8d 100644 --- a/docs/example/example-core/src/commonMain/kotlin/Example.kt +++ b/docs/example/example-core/src/commonMain/kotlin/Example.kt @@ -41,3 +41,10 @@ class Example { TODO() } } + +/** + * This is a top-level function. + */ +fun topLevelFunction(): Int { + TODO() +} diff --git a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt index 7fbd487..8ad2969 100644 --- a/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt +++ b/renderer/src/main/kotlin/renderer/MkDocsRenderer2.kt @@ -79,7 +79,7 @@ open class MkDocsRenderer2( buildComment { "TABLE NODE $node" } when (node.dci.kind) { - ContentKind.Packages -> { + ContentKind.Packages, ContentKind.Classlikes, ContentKind.Functions -> { for (pkg in node.children) { for (child in pkg.children) { when (child) { -- 2.51.2 From a19907fbd0b0ce6db43f77f55f29c120703d9f77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 3 Oct 2024 21:55:05 +0200 Subject: [PATCH 08/10] feat(example): Add documentation to the 'main' function --- docs/example/example-app/src/commonMain/kotlin/Main.kt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/example/example-app/src/commonMain/kotlin/Main.kt b/docs/example/example-app/src/commonMain/kotlin/Main.kt index 6fcb7a5..de63d12 100644 --- a/docs/example/example-app/src/commonMain/kotlin/Main.kt +++ b/docs/example/example-app/src/commonMain/kotlin/Main.kt @@ -1,5 +1,8 @@ package opensavvy.dokka.material.mkdocs.example +/** + * Main entry-point to the application. + */ fun main() { println("Hello world!") } -- 2.51.2 From 472d830ad3174648dd51f6036a6a81f986158e6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sun, 6 Oct 2024 19:15:50 +0200 Subject: [PATCH 09/10] build(idea): Remove old unused run configuration --- .../Generate_documentation_for_example.xml | 25 ------------------- 1 file changed, 25 deletions(-) delete mode 100644 .idea/runConfigurations/Generate_documentation_for_example.xml diff --git a/.idea/runConfigurations/Generate_documentation_for_example.xml b/.idea/runConfigurations/Generate_documentation_for_example.xml deleted file mode 100644 index baafe58..0000000 --- a/.idea/runConfigurations/Generate_documentation_for_example.xml +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - - true - false - false - false - - - \ No newline at end of file -- 2.51.2 From 53f19d11d2b61ce5fb38dc1da6224833dea0e246 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sun, 6 Oct 2024 19:16:59 +0200 Subject: [PATCH 10/10] feat(dokkatoo-mkdocs): Mark the generated documentation as experimental --- dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt b/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt index 907a1e5..0809524 100644 --- a/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt +++ b/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt @@ -63,7 +63,7 @@ abstract class DokkatooMkDocsPlugin : DokkatooFormatPlugin(formatName = "mkdocs" when { file == root -> { - builder.appendLine(" - Reference:") + builder.appendLine(" - Reference (experimental):") } file.isDirectory -> { -- 2.51.2