diff options
Diffstat (limited to 'mkdocs/src/doc')
28 files changed, 2792 insertions, 0 deletions
diff --git a/mkdocs/src/doc/docs/community/plugins-list.md b/mkdocs/src/doc/docs/community/plugins-list.md new file mode 100644 index 00000000..6ae8ce4c --- /dev/null +++ b/mkdocs/src/doc/docs/community/plugins-list.md @@ -0,0 +1,160 @@ +# Dokka community plugins + +On this page you can find `Dokka` plugins which are supported by both `Dokka` maintainers and community members. + +If you want to add your plugin to this list, get in touch with maintainers via [Slack](../community/slack.md) +or `GitHub`. + +If you want to learn how to develop plugins for `Dokka`, see +[Plugin development](../developer_guide/plugin-development/introduction.md) section. + +## Output Formats + +### Javadoc (Alpha) + +Javadoc plugin adds a `Javadoc` output format that looks like Java's `Javadoc`, but it's for the most part +a lookalike, so you may experience problems if you try to use it with a tool that expects native +`Javadoc` documentation generated by `Java`. + +`Javadoc` plugin does not support multiplatform projects and does not have a multi-module task. + +`Javadoc` plugin is shipped with `Dokka`, so you can start using it right away with one of the following tasks: + +* `dokkaJavadoc` - builds `Javadoc` documentation for single-module projects or for a specific module. +* `dokkaJavadocCollector` - collects generated `Javadoc` documentation from submodules and assembles it together. + +`Javadoc` plugin has its own signature provider that essentially translates `Kotlin` signatures to `Java` ones. + +**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to +[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. + +[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc) + +### GFM (Alpha) + +`GFM` plugins adds the ability to generate documentation in `GitHub flavoured Markdown` format. Supports both +multimodule and multiplatform projects, and is shipped together with `Dokka`, so you can start using it +right away with one of the following tasks: + +* `dokkaGfm` - generate documentation for a non multi-module project or one specific module. +* `dokkaGfmMultiModule` - generate documentation for a multi-module project, assemble it together and + generate navigation page/menu for all the modules. + +Example: + +___ + +//[dokka-debug-kts](#gfm)/[org.jetbrains.dokka.test](#gfm)/[MyClass](#gfm) + +#### MyClass + +[jvm] +class [MyClass](#gfm) + +KDoc that describes this class + +##### Constructors + +| | | +|---|---| +| [MyClass](#gfm) | [jvm]<br>fun [MyClass](#gfm)() | + +##### Functions + +| Name | Summary | +|------------------|---| +| [function](#gfm) | [jvm]<br>fun [function](#gfm)(): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment on top of this function | + +##### Properties + +| Name | Summary | +|---|------------------------------------------------------------------------------------------------------------------------------------------------| +| [property](#gfm) | [jvm]<br>val [property](#gfm): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment for a property | + +___ + +**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to +[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. + +[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/gfm) + +### Jekyll (Alpha) + +`Jekyll` plugins adds the ability to generate documentation in `Jekyll flavoured Markdown` format. Supports both +multi-module and multiplatform projects, and is shipped together with `Dokka`, so you can start using it +right away with one of the following tasks: + +* `dokkaJekyll` - generate documentation for a non multi-module project or one specific module. +* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and + generate navigation page/menu for all the modules. + +**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to +[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. + +[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll) + +## Extensions + +### Mathjax + +[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `MathJax` plugin +adds the ability to render mathematics from source code comments. + +If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` (ver. 2) with `config=TeX-AMS_SVG` +to generated `HTML` pages. + +Usage example: +```kotlin +/** + * Some math \(\sqrt{3x-1}+(1+x)^2\) + * + * @usesMathJax + */ +class Foo {} +``` + +Which results in: + +{ width="400" } + +[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) + +### Mermaid + +[Mermaid JS](https://mermaid-js.github.io/mermaid/#/) lets you create diagrams and visualizations using text and code. +`Mermaid` plugin allows rendering such diagrams and visualizations found in source code documentation. + +Usage example: +```kotlin +/** + * See the graph for more details: + * \```mermaid + * graph LR + * A[Christmas] -->|Get money| B(Go shopping) + * B --> C{Let me think} + * C -->|One| D[Laptop] + * C -->|Two| E[iPhone] + * C -->|Three| F[fa:fa-car Car] + * \``` + */ +class CompositeSubscription +``` + +Which results in: + +{ width="700" } + +For more information and examples, see +[Html Mermaid Dokka plugin](https://github.com/glureau/dokka-mermaid) repository on GitHub. + +### Kotlin as Java + +With `Kotlin as Java` plugin applied, all `Kotlin` signatures will be rendered as `Java` signatures. + +For instance, `fun foo(bar: Bar): Baz` will be rendered as `public final Baz foo(Bar bar)`. + +`Kotlin as Java` plugin is published to maven central as a +[separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin): +`org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20`. + +[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) diff --git a/mkdocs/src/doc/docs/community/slack.md b/mkdocs/src/doc/docs/community/slack.md new file mode 100644 index 00000000..290d4a18 --- /dev/null +++ b/mkdocs/src/doc/docs/community/slack.md @@ -0,0 +1,7 @@ +# Slack channel + +`Dokka` has a dedicated `#dokka` channel in the `Kotlin Community Slack`, where you can ask questions and chat +about using, customizing or contributing to `Dokka`. + +[Follow the instructions](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) +to get an invite or [connect directly](https://kotlinlang.slack.com). diff --git a/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md b/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md new file mode 100644 index 00000000..fb11f32a --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md @@ -0,0 +1,123 @@ +# Architecture overview + +Normally, you would think that a tool like `Dokka` simply parses some programming language sources and generates +`HTML` pages for whatever it sees along the way, with little to no abstractions. That would be the simplest and +shortest way to implement an API documentation engine. + +However, it was clear that `Dokka` may need to generate documentation from various sources (not only `Kotlin`), that users +might request additional output formats (like `Markdown`), that users might need additional features like supporting +custom `KDoc` tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside +`Dokka` itself if all solutions were hardcoded. + +For this reason, `Dokka` was built from the ground up to be easily extensible and customizable by adding several layers +of abstractions to the data model, and by providing pluggable extension points, giving you the ability to introduce +selective changes on a single level. + +## Overview of data model + +Generating API documentation begins with `Input` source files (`.kts`, `.java`, etc) and ends with some `Output` files +(`.html`/`.md` pages, etc). However, to allow for extensibility and customization, several input and output independent +abstractions have been added to the data model. + +Below you can find the general pipeline of processing data gathered from sources and the explanation for each stage. + +```mermaid +flowchart TD + Input --> Documentables --> Pages --> Output +``` + +* `Input` - generalization of sources, by default `Kotlin`/`Java` sources, but could be virtually anything +* `Documentables` - unified data model that represents _any_ parsed sources as a tree, independent of the source + language. Examples of a `Documentable`: class, function, package, property, etc +* `Pages` - universal model that represents output pages (e.g a function/property page) and the content it's composed of + (lists, text, code blocks) that the users needs to see. Not to be confused with `.html` pages. Goes hand in hand + with so-called `Content` model. +* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of pages/content model to + some human-readable and visual representation. For instance: + * `PageNode` is mapped as + * `.html` file for `HTML` format + * `.md` file for `Markdown` format + * `ContentList` is mapped as + * `<li>` / `<ul>` for `HTML` format + * `1.` / `*` for `Markdown` format + * `ContentCodeBlock` is mapped as + * `<code>` or `<pre>` with some CSS styles in `HTML` format + * Text wrapped in triple backticks for `Markdown` format + + +You, as a `Dokka` developer or a plugin writer, can use extension points to introduce selective changes to the +model on one particular level without touching everything else. + +For instance, if you wanted to make some annotation/function/class invisible in the final documentation, you would only +need to modify the `Documentables` model by filtering undesirable members out. If you wanted to display all overloaded +methods on the same page instead of on separate ones, you would only need to modify the `Page` model by merging multiple +pages into one, and so on. + +For a deeper dive into Dokka's model with more examples and details, +see sections about [Documentables](data_model/documentables.md) and [Page/Content](data_model/page_content.md) + +For an overview of existing extension points that let you transform Dokka's models, see +[Core extension points](extension_points/core_extensions.md) and [Base extensions](extension_points/base_extensions.md). + +## Overview of extension points + +An extension point usually represents some pluggable interface that performs an action during one of the stages of +generating documentation. An extension is therefore an implementation of that interface which is extending the +extension point. + +You can create extension points, provide your own implementations (extensions) and configure them. All of +this is possible with Dokka's plugin/extension point API. + +Here's a sneak peek of the DSL: + +```kotlin +class MyPlugin : DokkaPlugin() { + // create an extension point for other developers + val signatureProvider by extensionPoint<SignatureProvider>() + + // provide a default implementation + val defaultSignatureProvider by extending { + signatureProvider with KotlinSignatureProvider() + } + + // register our own extension in base plugin and override its default + val dokkaBasePlugin by lazy { plugin<DokkaBase>() } + val multimoduleLocationProvider by extending { + (dokkaBasePlugin.locationProviderFactory + providing MultimoduleLocationProvider::Factory + override dokkaBasePlugin.locationProvider) + } +} + +// use a registered extention, pretty much dependency injection +class MyExtension(val context: DokkaContext) { + + val signatureProvider: SignatureProvider = context.plugin<MyPlugin>().querySingle { signatureProvider } + + fun doSomething() { + signatureProvider.signature(..) + } +} + +interface SignatureProvider { + fun signature(documentable: Documentable): List<ContentNode> +} + +class KotlinSignatureProvider : SignatureProvider { + override fun signature(documentable: Documentable): List<ContentNode> = listOf() +} +``` + +For a deeper dive into extensions and extension points with more examples and details, see +[Introduction to Extensions](extension_points/introduction.md). + +For an overview of existing extension points, see [Core extension points](extension_points/core_extensions.md) and +[Base extensions](extension_points/base_extensions.md). + +## Historical context + +This is a second iteration of Dokka that was built from scratch. + +If you want to learn more about why Dokka has been designed this way, watch this great talk by Paweł Marks: +[New Dokka - Designed for Fearless Creativity](https://www.youtube.com/watch?v=OvFoTRhqaKg). The general principles +and general architecture are the same, although it may be outdated in some areas, so please double-check. diff --git a/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md new file mode 100644 index 00000000..5264553d --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md @@ -0,0 +1,245 @@ +# Documentables Model + +Documentables represent data that is parsed from sources. Think of this data model as of something that could be +seen or produced by a compiler frontend, it's not far off from the truth. + +By default, documentables are parsed from `Descriptor` (for `Kotlin`) +and [Psi](https://plugins.jetbrains.com/docs/intellij/psi.html) +(for `Java`) models. Code-wise, you can have a look at following classes: + +* `DefaultDescriptorToDocumentableTranslator` - responsible for `Kotlin` -> `Documentable` mapping +* `DefaultPsiToDocumentableTranslator` - responsible for `Java` -> `Documentable` mapping + +Upon creation, it's a collection of trees, each with `DModule` as root. + +Take some arbitrary `Kotlin` source code that is located within the same module: + +```kotlin +// Package 1 +class Clazz(val property: String) { + fun function(parameter: String) {} +} + +fun topLevelFunction() {} + +// Package 2 +enum class Enum { } + +val topLevelProperty: String +``` + +This would be represented roughly as the following `Documentable` tree: + +```mermaid +flowchart TD + DModule --> firstPackage[DPackage] + firstPackage --> DClass + firstPackage --> toplevelfunction[DFunction] + DClass --> DProperty + DClass --> DFunction + DFunction --> DParameter + DModule --> secondPackage[DPackage] + secondPackage --> DEnum + secondPackage --> secondPackageProperty[DProperty] +``` + +At later stages of transformation, all trees are folded into one (by `DocumentableMerger`). + +## Documentable + +The main building block of documentables model is `Documentable` class. It's the base class for all more specific types +that represent elements of parsed sources with mostly self-explanatory names (`DFunction`, `DPackage`, `DProperty`, etc) +. +`DClasslike` is the base class for class-like documentables such as `DClass`, `DEnum`, `DAnnotation`, etc. + +The contents of each documentable normally represent what you would see in source code. For instance, if you open +`DClass`, you should find that it contains references to functions, properties, companion object, constructors and so +on. +`DEnum` should have references to enum entries, and `DPackage` can have references to both classlikes and top-level +functions and properties (`Kotlin`-specific). + +Here's an example of a documentable: + +```kotlin +data class DClass( + val dri: DRI, + val name: String, + val constructors: List<DFunction>, + val functions: List<DFunction>, + val properties: List<DProperty>, + val classlikes: List<DClasslike>, + val sources: SourceSetDependent<DocumentableSource>, + val visibility: SourceSetDependent<Visibility>, + val companion: DObject?, + val generics: List<DTypeParameter>, + val supertypes: SourceSetDependent<List<TypeConstructorWithKind>>, + val documentation: SourceSetDependent<DocumentationNode>, + val expectPresentInSet: DokkaSourceSet?, + val modifier: SourceSetDependent<Modifier>, + val sourceSets: Set<DokkaSourceSet>, + val isExpectActual: Boolean, + val extra: PropertyContainer<DClass> = PropertyContainer.empty() +) : DClasslike(), WithAbstraction, WithCompanion, WithConstructors, + WithGenerics, WithSupertypes, WithExtraProperties<DClass> +``` + +___ + +There are three non-documentable classes that important for this model: + +* `DRI` +* `SourceSetDependent` +* `ExtraProperty`. + +### DRI + +`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies a specific `Documentable`. +All references and relations between documentables (other than direct ownership) are described using `DRI`. + +For example, `DFunction` with a parameter of type `Foo` has only `Foo`'s `DRI`, not the actual reference +to `Foo`'s `Documentable` object. + +#### Example + +For an example of how a `DRI` can look like, let's take the `limitedParallelism` function from `kotlinx.coroutines`: + +```kotlin +package kotlinx.coroutines + +import ... + +public abstract class MainCoroutineDispatcher : CoroutineDispatcher() { + + override fun limitedParallelism(parallelism: Int): CoroutineDispatcher { + ... + } +} +``` + +If we were to re-create the DRI of this function in code, it would look something like this: + +```kotlin +DRI( + packageName = "kotlinx.coroutines", + classNames = "MainCoroutineDispatcher", + callable = Callable( + name = "limitedParallelism", + receiver = null, + params = listOf( + TypeConstructor( + fullyQualifiedName = "kotlin.Int", + params = emptyList() + ) + ) + ), + target = PointingToDeclaration, + extra = null +) +``` + +If you format it as `String`, it would look like this: + +``` +kotlinx.coroutines/MainCoroutineDispatcher/limitedParallelism/#kotlin.Int/PointingToDeclaration/ +``` + +### SourceSetDependent + +`SourceSetDependent` helps handling multiplatform data by associating platform-specific data (declared with either +`expect` or `actual` modifier) with particular +[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets). + +This comes in handy if `expect`/`actual` declarations differ. For instance, the default value for `actual` might differ +from that declared in `expect`, or code comments written for `expect` might be different from what's written +for `actual`. + +Under the hood, it's a `typealias` to a `Map`: + +```kotlin +typealias SourceSetDependent<T> = Map<DokkaSourceSet, T> +``` + +### ExtraProperty + +`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly +recommended to use extras to provide any additional information when creating custom Dokka plugins. + +This element is a bit more complex, so you can read more about how to use it +[in a separate section](extra.md). + +___ + +## Documentation model + +Documentation model is used alongside Documentables to store data obtained by parsing +code comments (such as `KDoc`/`Javadoc`). + +### DocTag + +`DocTag` describes a specific documentation syntax element. + +It's universal across source languages. For instance, DocTag `B` is the same for `**bold**` in `Kotlin` and +`<b>bold</b>` in `Java`. + +However, some `DocTag` elements are specific to a certain language, there are many such examples for `Java` +because it allows HTML tags inside `Javadoc` comments, some of which are simply not possible to reproduce with `Markdown`. + +`DocTag` elements can be deeply nested with other `DocTag` children elements. + +Examples: + +```kotlin +data class H1( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : DocTag() + +data class H2( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : DocTag() + +data class Strikethrough( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : DocTag() + +data class Strong( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : DocTag() + +data class CodeBlock( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : Code() + +``` + +### TagWrapper + +`TagWrapper` describes the whole comment description or a specific comment tag. +For example: `@see` / `@author` / `@return`. + +Since each such section may contain formatted text inside of it, each `TagWrapper` has `DocTag` children. + +```kotlin +/** + * @author **Ben Affleck* + * @return nothing, except _sometimes_ it may throw an [Error] + */ +fun foo() {} +``` + +### DocumentationNode + +`DocumentationNode` acts as a container for multiple `TagWrapper` elements for a specific `Documentable`, usually +used like this: + +```kotlin +data class DFunction( + ... + val documentation: SourceSetDependent<DocumentationNode>, + ... +) +``` diff --git a/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md new file mode 100644 index 00000000..0abbc70e --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md @@ -0,0 +1,99 @@ +# Extra + +## Introduction + +`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md#content-model) +models. + +Source code for `ExtraProperty`: + +```kotlin +interface ExtraProperty<in C : Any> { + interface Key<in C : Any, T : Any> { + fun mergeStrategyFor(left: T, right: T): MergeStrategy<C> = MergeStrategy.Fail { + throw NotImplementedError("Property merging for $this is not implemented") + } + } + + val key: Key<C, *> +} +``` + +To declare a new extra, you need to implement `ExtraProperty` interface. It is advised to use following pattern +when declaring new extras: + +```kotlin +data class CustomExtra( + [any data relevant to your extra], + [any data relevant to your extra] +): ExtraProperty<Documentable> { + override val key: CustomExtra.Key<Documentable, *> = CustomExtra + companion object : CustomExtra.Key<Documentable, CustomExtra> +} +``` + +Merge strategy (`mergeStrategyFor` method) for extras is invoked during +[merging](../extension_points/core_extensions.md#documentablemerger) if documentables from different +[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) each +have their own `Extra` of the same type. + +## PropertyContainer + +All extras for `ContentNode` and `Documentable` classes are stored in `PropertyContainer<C : Any>` class instances. + +```kotlin +data class DFunction( + ... + override val extra: PropertyContainer<DFunction> = PropertyContainer.empty() + ... +) : WithExtraProperties<DFunction> +``` + +`PropertyContainer` has a number of convenient functions for handling extras in a collection-like manner. + +The `C` generic class parameter limits the type of properties that can be stored in the container - it must +match generic `C` class parameter from `ExtraProperty` interface. This allows creating extra properties +which can only be stored in a specific `Documentable`. + +## Usage example + +In following example we will create a `DFunction`-only property, store it and then retrieve its value: + +```kotlin +data class CustomExtra(val customExtraValue: String) : ExtraProperty<DFunction> { + override val key: ExtraProperty.Key<Documentable, *> = CustomExtra + companion object: ExtraProperty.Key<Documentable, CustomExtra> +} + +fun DFunction.withCustomExtraProperty(data: String): DFunction { + return this.copy( + extra = extra + CustomExtra(data) + ) +} + +fun DFunction.getCustomExtraPropertyValue(): String? { + return this.extra[CustomExtra]?.customExtraValue +} +``` + +___ + +You can also use extras as markers, without storing any data in them: + +```kotlin + +object MarkerExtra : ExtraProperty<Any>, ExtraProperty.Key<Any, MarkerExtra> { + override val key: ExtraProperty.Key<Any, *> = this +} + +fun Documentable.markIfFunction(): Documentable { + return when(this) { + is DFunction -> this.copy(extra = extra + MarkerExtra) + else -> this + } +} + +fun WithExtraProperties<Documentable>.isMarked(): Boolean { + return this.extra[MarkerExtra] != null +} +``` diff --git a/mkdocs/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/page_content.md new file mode 100644 index 00000000..54ded235 --- /dev/null +++ b/mkdocs/src/doc/docs/developer_guide/architecture/data_model/page_content.md @@ -0,0 +1,140 @@ +# Page / Content Model + +Even though `Page` and `Content` models reside on the same level (under `Page`), it's easier to view it as two different +models altogether, even though `Content` is only used in conjunction with and inside `Page` model. + +## Page + +Page model represents the structure of documentation pages to be generated. During rendering, each page +is processed separately, so one page corresponds to exactly one output file. + +Page model is independent of the final output format, in other words it's universal. Which extension the pages +should be created as (`.html`, `.md`, etc) and how is up to the `Renderer`. + +Subclasses of `PageNode` represent different kinds of rendered pages, such as `ModulePage`, `PackagePage`, +`ClasslikePage`, `MemberPage` (properties, functions), etc. + +The Page Model is a tree structure, with `RootPageNode` at the root. + +Here's an example of how an arbitrary `Page` tree might look like for a module with 3 packages, one of which contains +a top level function, top level property and a class, inside which there's a function and a property: + +```mermaid +flowchart TD + RootPageNode --> firstPackage[PackagePageNode] + RootPageNode --> secondPackage[PackagePageNode] + RootPageNode --> thirdPackage[PackagePageNode] + firstPackage --> firstPackageFirstMember[MemberPageNode - Function] + firstPackage --> firstPackageSecondMember[MemberPageNode - Property] + firstPackage ---> firstPackageClasslike[ClasslikePageNode - Class] + firstPackageClasslike --> firstPackageClasslikeFirstMember[MemberPageNode - Function] + firstPackageClasslike --> firstPackageClasslikeSecondMember[MemberPageNode - Property] + secondPackage --> etcOne[...] + thirdPackage --> etcTwo[...] +``` + +Almost all pages are derivatives of `ContentPage` - it's the type of `Page` that has `Content` on it. + +## Content Model + +Content model describes how the actual `Page` content is presented. The important thing to understand is that it's +also output-format independent and is universal. + +Content model is essentially a set of building blocks that you can put together to represent some content. +Have a look at subclasses of `ContentNode`: `ContentText`, `ContentList`, `ContentTable`, `ContentCodeBlock`, +`ContentHeader` and so on. You can group content together with `ContentGroup` - for instance, +to wrap all children with some style. + +```kotlin +// real example of composing content using `DocumentableContentBuilder` DSL +orderedList { + item { + text("This list contains a nested table:") + table { + header { + text("Col1") + text("Col2") + } + row { + text("Text1") + text("Text2") + } + } + } + item { + group(styles = setOf(TextStyle.Bold)) { + text("This is bald") + text("This is also bald") + } + } +} +``` + +It is then responsibility of `Renderer` (i.e specific output format) to r |