Add an example plugin and "creating a plugin" tutorial

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. 

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

@@ -6,19 +6,18 @@ TODO add a link on how to apply plugins
 
 ### Javadoc (Alpha)
 
-Javadoc plugin adds a Javadoc output format looks like Java's Javadoc, but it's for the most part
+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
-Javadocs generated by Java.
+`Javadocs` generated by `Java`.
 
-Javadoc plugin does not support multiplatform projects and does not have a multi-module task.
+`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:
+`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.
+* `dokkaJavadoc` - builds `Javadoc` documentation for single-module projects or for a specific module.
+* `dokkaJavadocCollector` - collects generated `Javadoc` documentation from submodules and assembles it together.
 
-* TODO add an example or a screenshot
-* TODO copy description to the source code 
+`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.
@@ -27,16 +26,46 @@ Javadoc plugin is shipped with Dokka, so you can start using it right away with
 
 ### GFM (Alpha)
 
-GFM plugins adds an ability to generate documentation in GitHub flavoured Markdown format. Supports both
-multi-module and multiplatform projects, and is shipped together with Dokka, so you can start using it
+`GFM` plugins adds an 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.
 
-* TODO add an example or a screenshot
-* TODO copy description to the source code
+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.
@@ -45,17 +74,14 @@ right away with one of the following tasks:
 
 ### Jekyll (Alpha)
 
-Jekyll plugins adds an 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
+`Jekyll` plugins adds an 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.
 
-* TODO add an example or a screenshot
-* TODO copy description to the source code
-
 **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.
 
@@ -65,44 +91,44 @@ right away with one of the following tasks:
 
 ### Mathjax
 
-[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. Dokka MathJax plugin
+[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `Dokka` `MathJax` plugin
 adds an ability to render mathematics from source code comments.
 
-If MathJax plugin encounters `@usesMathJax` KDoc tag, it adds `MathJax.js` 2.7.6 with `config=TeX-AMS_SVG`
-to generated HTML pages.
+If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` 2.7.6 with `config=TeX-AMS_SVG`
+to generated `HTML` pages.
 
 Usage example:
 ```kotlin
 /**
  * @usesMathJax
  *
- * \(\sqrt{3x-1}+(1+x)^2\)
+ * Some math \(\sqrt{3x-1}+(1+x)^2\)
  */
-class Clazz {}
+class Foo {}
 ```
 
-TODO add a screenshot
+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.
+`Mermaid` plugin allows rendering such diagrams and visualizations found in source code documentation.
 
 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)`.
+With `Kotlin as Java` plugin applied, all `Kotlin` signatures will be rendered as `Java` signatures. 
 
-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.6.21`. See instructions on how to apply it. 
+For instance, `fun foo(bar: Bar): Baz` will be rendered as `public final Baz foo(Bar bar)`.
 
-TODO insert applying link
-TODO insert screenshot
+`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.6.21`. 
 
 [Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java)

docs/src/doc/docs/developer_guide/architecture/architecture_overview.md

@@ -63,11 +63,12 @@ class MyPlugin : DokkaPlugin() {
         signatureProvider with KotlinSignatureProvider()
     }
 
-    // register our own extension in someone else's plugin and override its default
+    // register our own extension in another plugin and override its default
     val dokkaBasePlugin by lazy { plugin<DokkaBase>() }
-    val customOutputWriter by extending {
-        (dokkaBasePlugin.outputWriter with MyOutputWriter()
-                override dokkaBasePlugin.fileWriter)
+    val multimoduleLocationProvider by extending {
+        (dokkaBasePlugin.locationProviderFactory
+                providing MultimoduleLocationProvider::Factory
+                override dokkaBasePlugin.locationProvider)
     }
 }
 
@@ -88,3 +89,11 @@ class KotlinSignatureProvider : SignatureProvider {
     override fun signature(documentable: Documentable): List<ContentNode> = listOf()
 }
 ```
+
+## 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.

docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md

@@ -8,8 +8,5 @@ plugin that only needs to provide a few extensions or change a single place and
 
 `DokkaBase` is used extensively for Dokka's own output formats such as `HTML`, `Markdown`, `Mathjax` and others.
 
-If you are developing a plugin, you can find more information on how to use defaults and extension points from 
-`DokkaBase` in [Introduction to Plugin development](../../plugin-development/introduction.md). 
-
 You can learn how to add/use/override/configure extensions and extension points in
-[Introduction to Extensions](introduction.md), all of the information is applicable to `DokkaBase`.
+[Introduction to Extensions](introduction.md), all the information is applicable to `DokkaBase` plugin as well.

docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md

@@ -6,7 +6,7 @@ These extension points are plugin and output format independent, meaning it's th
 low-level as can get. For higher-level extension functions that can be used in different output formats, have a look at
 [Base extensions](base_extensions.md) defined in `DokkaBase`.
 
-You can find all extensions in `CoreExtensions` class:
+You can find all core extensions in `CoreExtensions` class:
 ```kotlin
 object CoreExtensions {
     val preGenerationCheck by coreExtensionPoint<PreGenerationChecker>()

docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md

@@ -1,4 +1,4 @@
-# Introduction to Extension Points
+# Overview
 
 In this section you can learn how to create new extension points, how to use and configure existing ones and
 how to query for extensions when generating documentation.

docs/src/doc/docs/developer_guide/introduction.md

@@ -1,4 +1,19 @@
-# Introduction to Dokka Plugin development
+# Developer guides
 
+The purpose of `Developer guides` section is to get you acquainted with Dokka's internals so that you can start developing
+your own plugins or contributing features and fixes to Dokka itself.
 
+If you want to start hacking on Dokka right away, the only thing you need to be aware of is the
+[general workflow](workflow.md), it will teach you how to build, debug and test Dokka.
 
+If you want to get into plugin development quick, see
+[Introduction to plugin development](plugin-development/introduction.md).
+
+If you have time to spare and want to know more about Dokka's internals, its architecture and capabilities, follow
+[Architecture overview](architecture/architecture_overview.md) and subsequent sections.
+
+Having read through all the developer guides, you'll have a pretty good unrestanding of Dokka and how to develop
+for it. 
+
+If you have any questions, feel free to get in touch with maintainers via [Slack](../community/slack.md) or 
+[GitHub](https://github.com/kotlin/dokka).

docs/src/doc/docs/developer_guide/plugin-development/introduction.md

@@ -1,8 +1,20 @@
-## Configuration
+# Plugin Development
 
-tldr: you can use a convenient [plugin template](https://github.com/Kotlin/dokka-plugin-template) to speed up the setup.
+In order to have an easier time developing plugins, it's a good idea to go through
+[Dokka's internals](../architecture/architecture_overview.md) to learn more about
+[extensions](../architecture/extension_points/introduction.md) and
+[data model](../architecture/data_model/documentables.md).
 
-Dokka requires configured `Kotlin plugin` and `dokka-core` dependency.
+## Setup
+
+### Template 
+
+The easiest way to start is to use a convenient [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template).
+It has pre-configured dependencies, publishing and signing of your artifacts.
+
+### Manual
+
+At a bare minimum, Dokka requires `Kotlin Gradle Plugin` and `dokka-core` dependencies:
 
 ```kotlin
 plugins {
@@ -18,51 +30,30 @@ tasks.withType<KotlinCompile> {
 }
 ```
 
-### Registering extension point
+In order to load a plugin into Dokka, your class must extend `DokkaPlugin` class. A fully qualified name of that class
+must be placed in a file named `org.jetbrains.dokka.plugability.DokkaPlugin` under `resources/META-INF/services`. 
+All instances are automatically loaded during Dokka setup using `java.util.ServiceLoader`.
 
-You can register your own extension point using `extensionPoint` function declared in `DokkaPlugin` class
+## Extension points 
 
-```kotlin
-class SamplePlugin : DokkaPlugin() {
-    val extensionPoint by extensionPoint<SampleExtensionPointInterface>()
-}
+Dokka provides a set of entry points for which you can create your own implementations. If you are not sure which
+extension point to use, have a look at [core extensions](../architecture/extension_points/core_extensions.md) and
+[base extensions](../architecture/extension_points/base_extensions.md) - it might give you a general direction.
 
-interface SampleExtensionPointInterface
-```
+You can learn how to declare extension points and use extensions in
+[Introduction to Extension points](../architecture/extension_points/introduction.md).
 
-### Obtaining extension instance
+In case no suitable extension point exists for your use case, do share the details - it might be added in future
+versions of Dokka.
 
-All registered plugins are accessible with `DokkaContext.plugin` function. All plugins that extends `DokkaPlugin` can use `DokkaPlugin.plugin` function, that uses underlying `DokkaContext` instance. If you want to pass context to your extension, you can obtain it using aforementioned `providing` infix function.
+## Example
 
-With plugin instance obtained, you can browse extensions registered for this plugins' extension points using `querySingle` and `query` methods:
+You can follow [a simple plugin guide](simple-plugin-guide.md) which covers creation of a simple plugin: hide members
+annotated with `@Internal` annotation, i.e exclude them from generated documentation.
 
-```kotlin
-    context.plugin<DokkaBase>().query { htmlPreprocessors }
-    context.plugin<DokkaBase>().querySingle { samplesTransformer }
-```
+Fore more practical examples, have a look at sources of [community plugins](../../community/plugins-list.md).
 
-You can also browse `DokkaContext` directly, using `single` and `get` methods:
+## Help
 
-```kotlin
-class SamplePlugin : DokkaPlugin() {
-
-    val extensionPoint by extensionPoint<SampleExtensionPointInterface>()
-    val anotherExtensionPoint by extensionPoint<AnotherSampleExtensionPointInterface>()
-
-    val extension by extending {
-        extensionPoint with SampleExtension()
-    }
-
-    val anotherExtension by extending { 
-        anotherExtensionPoint providing { context ->
-            AnotherSampleExtension(context.single(extensionPoint))
-        }
-    }
-}
-
-interface SampleExtensionPointInterface
-interface AnotherSampleExtensionPointInterface
-
-class SampleExtension: SampleExtensionPointInterface
-class AnotherSampleExtension(sampleExtension: SampleExtensionPointInterface): AnotherSampleExtensionPointInterface
-```
+If you have any further questions, feel free to get in touch with maintainers via [Slack](../../community/slack.md) or
+[GitHub](https://github.com/kotlin/dokka).