Revise developer guides documentation

CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+## Code of Conduct
+
+This project and the corresponding community is governed by the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct).
+Please make sure you read it. 

buildSrc/src/main/kotlin/org/jetbrains/publication.kt

@@ -100,7 +100,7 @@ fun Project.configureSonatypePublicationIfNecessary(vararg publications: String)
 fun MavenPublication.configurePom(projectName: String) {
     pom {
         name.set(projectName)
-        description.set("Dokka is a documentation engine for Kotlin and Java, performing the same function as Javadoc for Java")
+        description.set("Dokka is an API documentation engine for Kotlin and Java, performing the same function as Javadoc for Java")
         url.set("https://github.com/Kotlin/dokka")
 
         licenses {

core/src/main/kotlin/pages/ContentNodes.kt

@@ -317,9 +317,8 @@ interface Style
 interface Kind
 
 /**
- * [ContentKind] represents a grouping of content of one kind. This can be rendered
- * as either a part of a composite page (one tab/block within a class's page, for instance)
- * or as a separate page altogether.
+ * [ContentKind] represents a grouping of content of one kind that can can be rendered
+ * as part of a composite page (one tab/block within a class's page, for instance).
  */
 enum class ContentKind : Kind {
 

docs/src/doc/docs/community/plugins-list.md

@@ -1,18 +1,160 @@
 # Dokka community plugins
 
-Here is a list of plugins created by dokka team or community.
+On this page you can find `Dokka` plugins which are supported by both `Dokka` maintainers and community members.
 
-In order to add your plugin to this list it needs to be:
+If you want to add your plugin to this list, get in touch with maintainers via [Slack](../community/slack.md)
+or `GitHub`.
 
- * an open source project - sharing is caring so let others learn and improve your plugin
- * present in any public artefacts repository like bintray
+If you want to learn how to develop plugins for `Dokka`, see 
+[Plugin development](../developer_guide/plugin-development/introduction.md) section.
 
-| Plugin name | Description | Source |
-| :--------- | :--------- | :------------ |
-| [Kotlin as Java](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Display Kotlin code as seen from Java | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java)
-| [GFM](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a GFM format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/gfm)
-| [Javadoc](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a Javadoc format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc)
-| [Jekyll](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a Jekyll format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll)
-| [Mermaid-HTML](https://mermaid-js.github.io/mermaid/#/) | Renders Mermaid graphs for HTML renderer. | [Github](https://github.com/glureau/dokka-mermaid)
+## 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:
+
+![Mathjax demo](../images/mathjax_demo.png){ 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:
+
+![Mermaid demo](../images/mermaid_demo.png){ 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.0`. 
+
+[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java)

docs/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). 

docs/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.