New Dokka - Designed for Fearless Creativity

Pluggability is hard. Many software projects avoid it by all means possible. Many try to contain it in the smallest possible scope. We believe that developers are creative and have specific requirements for their documentation engine. Some of them want to be able to render their docs in javadoc-compatible format. Some of them want features like a full-text search or runnable code snippets inside of the docs. And there are some that need features that we’ve never even thought about. To satisfy all of them, we decided to embrace full pluggability. And we decided to make pluggability fearless, so anyone can mix and match existing plugins or easily create new ones from scratch, without the fear of breaking anything.

In my talk, I would like to tell you how we decided to redesign and reimplement Dokka from scratch. I will introduce you to all the dangers and risks of pluggability and tell you how we mitigated them by design, grounded in strong guarantees. Finally, I want to show how easily and how much you can do with your old, boring documentation using new Dokka.

Transcript

1. New Dokka - Designed for Fearless Creativity Paweł Marks
2. ...or why we reimplemented documentation engine from the scratch Paweł Marks
3. ...or how to be flexible without worries Paweł Marks
4. Docs - it just works right?
5. Docs - it just works
6. Docs - it just works
7. Dokka - more features? •HTML •Markdown •Javadoc •Parsing Java code •Synthetic symbols •Code samples •Documentation for REST •Advanced search •Platform markers •Integration with github
8. Solved with formatters •HTML •Markdown •Javadoc •Parsing Java code •Synthetic symbols •Code samples •Documentation for REST •Advanced search •Platform markers •Integration with github
9. Hardcoded solutions •HTML •Markdown •Javadoc •Parsing Java code •Synthetic symbols •Code samples •Documentation for REST •Advanced search •Platform markers •Integration with github
10. Solved with binary patching •HTML •Markdown •Javadoc •Parsing Java code •Synthetic symbols •Code samples •Documentation for REST •Advanced search •Platform markers •Integration with github
11. Why it is not maintainable •Inability to cooperate between “plugins” •Model becoming more and more dissolved •Lack of guarantees
12. The New Dokka Pluggability is the answer
15. The New Dokka Pluggability is the answer
16. The New Dokka Let’s create plugin…
17. The problem /** * A sample extension function * When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) * and they are $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$ * @usesMathJax */ fun Clock.extensionFun() { }
18. The problem
19. The solution
20. The solution plugins { kotlin("jvm") version "1.3.72" } group "org.example" version "1.0-SNAPSHOT" repositories { mavenCentral() mavenLocal() } dependencies { implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8") compileOnly("org.jetbrains.dokka:dokka-core:0.11.0-SNAPSHOT") }
21. The solution org.example.MathjaxPlugin
22. The solution package org.example import org.jetbrains.dokka.plugability.DokkaPlugin class MathjaxPlugin: DokkaPlugin() { }
23. Plugins Plugin = extensions + extension points
24. Plugins extensions extension points
25. The model
26. The models Input Documentables Pages Output
27. The models Input Documentables Pages Output Kotlin sources Java sources …
28. The models Input Documentables Pages Output { package } { class } { function } { method } { property }
29. New Dokka Input Documentables Pages Output class index package index search page function doc module index
30. The models Input Documentables Pages Output class index header(“class Abc”) block(“methods”) { group { text(“fun add”) signature(…) text(“some docs”) … } … }
31. The models Input Documentables Pages Output HTML Markdown …
32. Extension Points Input Documentables Pages Output documentableTransformer: documentableToPageTranslator: renderer: sourceToDocumentableTranslator: pageTransformer:
33. Extensions Input Documentables Pages Output forJava forKotlin syntheticFunctionsGenerator defaultTranslator functionMerger navigationGenerator HTMLRenderer documentableTransformer: documentableToPageTranslator: renderer: sourceToDocumentableTranslator: pageTransformer:
34. Our extension class MathjaxPlugin: DokkaPlugin() { val mathjaxTransformer by extending { } }
35. Our extension class MathjaxPlugin: DokkaPlugin() { val mathjaxTransformer by extending { CoreExtensions.pageTransformer with } }
36. Our extension class MathjaxPlugin: DokkaPlugin() { val mathjaxTransformer by extending { CoreExtensions.pageTransformer with MathjaxTransformer } } object MathjaxTransformer
37. Our extension object MathjaxTransformer : PageTransformer { override fun invoke(input: RootPageNode): RootPageNode { TODO("Not yet implemented") } } interface ContentPage: PageNode { val content: ContentNode val dri: Set<DRI> val documentable: Documentable? val embeddedResources: List<String> … }
38. Our extension private const val ANNOTATION = "usesMathJax" private const val LIB_PATH = “https://cdnjs.cloudflare.com/ajax/libs/mathjax/… object MathjaxTransformer : PageTransformer { override fun invoke(input: RootPageNode) = input.transformContentPagesTree { it.modified( embeddedResources = it.embeddedResources + if (it.isNeedingMathjax) listOf(LIB_PATH) else emptyList() ) } }
39. Our extension private const val ANNOTATION = "usesMathJax" private const val LIB_PATH = “https://cdnjs.cloudflare.com/ajax/libs/mathjax/… object MathjaxTransformer : PageTransformer { override fun invoke(input: RootPageNode) = … private val ContentPage.isNeedingMathjax get() = documentable?.documentation?.values ?.flatMap { it.children } .orEmpty() .any { (it as? CustomWrapperTag)?.name == ANNOTATION } }
40. package org.example import . . . class MathjaxPlugin: DokkaPlugin() { val mathjaxTransformer by extending { CoreExtensions.pageTransformer with MathjaxTransformer } } private const val ANNOTATION = "usesMathJax" private const val LIB_PATH = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.6/MathJax.js?config=TeX-AMS_SVG&latest" object MathjaxTransformer : PageTransformer { override fun invoke(input: RootPageNode) = input.transformContentPagesTree { it.modified( embeddedResources = it.embeddedResources + if (it.isNeedingMathjax) listOf(LIB_PATH) else emptyList() ) } private val ContentPage.isNeedingMathjax get() = documentable?.documentation?.values ?.flatMap { it.children } .orEmpty() .any { (it as? CustomWrapperTag)?.name == ANNOTATION } }
41. dependencies { implementation(“org.jetbrains.kotlin:kotlin-stdlib-jdk8") . . . dokkaPlugin(project(“:mathjax-plugin“)) } The solution
42. dependencies { implementation(“org.jetbrains.kotlin:kotlin-stdlib-jdk8") . . . dokkaPlugin(“org.example:mathjax-plugin“) } The solution Loaded plugins: [org.example.MathjaxPlugin, org.jetbrains.dokka.base.DokkaBase]
43. The solution https://github.com/Kotlin/dokka/tree/dev-0.11.0/plugins/mathjax
44. Plugins - it just works
45. Plugins - it just works?
46. Guarantees for the rescue •Typesafe plugin dependencies
47. Plugin dependencies class MyPlugin : DokkaPlugin() { val transformer by extending { CoreExtensions.pageTransformer with MyTransformer order { after(plugin<Synthetic>.generateSyntheticFunction) } } val myrendererHelper by extending { plugin<HelpersPlugin>.renderer with MyRendererHelper } }
48. Guarantees for the rescue •Typesafe plugin dependencies •Immutability •Contextlessness
49. Contextlessness class index package index function doc class index package index function doc
50. Guarantees for the rescue •Typesafe plugin dependencies •Immutability •Identifiability •Contextlessness
51. Idenifiability class index package index properties doc { class } { property } { … }
52. Guarantees for the rescue •Typesafe plugin dependencies •Immutability •Identifiability •Contextlessnes
53. Conclussion
54. New dokka is comming out soon
55. New dokka will be better looking, more consistent and flexible than ever
56. Strong guarantees are a key to extensibility
57. Thank you!