Exclude user guides from mkdocs documentation (#2868)

Kotlin · Feb 20, 2023 · 5762271 · 5762271
1 parent 1e10c6f
commit 5762271
Show file tree

Hide file tree

Showing 16 changed files with 56 additions and 1,278 deletions.
diff --git a/mkdocs/README.md b/mkdocs/README.md
@@ -0,0 +1,33 @@
+# MkDocs documentation
+
+This module contains documentation which is published to GitHub pages: 
+[kotlin.github.io/dokka](https://kotlin.github.io/dokka/).
+
+It is built using the [gradle-mkdocs-plugin](https://github.com/xvik/gradle-mkdocs-plugin).
+
+## Building
+
+You can build the documentation locally:
+
+```Bash
+./gradlew :mkdocs:mkdocsBuild
+```
+
+The output directory is `build/mkdocs`
+
+### Livereload server
+
+Alternatively, you can run a livereload server that automatically rebuilds documentation on every change:
+
+```Bash
+./gradlew :mkdocs:mkdocsServe
+```
+
+By default, it is run under [127.0.0.1:3001](http://127.0.0.1:3001/), but you can change it in 
+[mkdocs.yml](src/doc/mkdocs.yml) by setting the `dev_addr` option.
+
+## Publishing
+
+The documentation is published automatically for all changes in master and for every GitHub release.
+
+See [gh-pages.yml](../.github/workflows/gh-pages.yml) workflow configuration for more details.
diff --git a/mkdocs/src/doc/docs/community/plugins-list.md b/mkdocs/src/doc/docs/community/plugins-list.md
diff --git a/...s/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md b/...s/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md
@@ -147,5 +147,5 @@ and `CommonmarkRenderer`.
 `PostAction` is useful for when you want to run some actions after the documentation has been generated - for instance
 if you want to move some files around.
 
-[Versioning plugin](../../../user_guide/plugins/versioning-plugin.md) utilizes `PostAction` in order to move
+[Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) utilizes `PostAction` in order to move
 generated documentation to versioned folders.
diff --git a/mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md b/mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md
@@ -1,5 +1,13 @@
 # Introduction to plugin development
 
+Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community to 
+implement plugins for missing or very specific features that are not provided out of the box.
+
+Dokka plugins range anywhere from supporting other programming language sources to exotic output formats. You can add 
+support for your own KDoc tags or annotations, teach Dokka how to render different DSLs that are found in KDoc 
+descriptions, visually redesign Dokka's pages to be seamlessly integrated into your company's website, integrate 
+it with other tools and so much more.
+
 In order to have an easier time developing plugins, it's a good idea to go through
 [Dokka's internals](../architecture/architecture_overview.md) first to learn more about its
 [data model](../architecture/data_model/documentables.md) and 
@@ -51,7 +59,8 @@ versions of Dokka.
 You can follow the [sample plugin tutorial](sample-plugin-tutorial.md) which covers creation of a simple plugin: hide members
 annotated with your own `@Internal` annotation, that is exclude these members from generated documentation.
 
-Fore more practical examples, have a look at sources of [community plugins](../../community/plugins-list.md).
+Fore more practical examples, have a look at sources of 
+[community plugins](https://kotlinlang.org/docs/dokka-plugins.html#notable-plugins).
 
 ## Help
 

diff --git a/mkdocs/src/doc/docs/faq.md b/mkdocs/src/doc/docs/faq.md
diff --git a/mkdocs/src/doc/docs/images/mathjax_demo.png b/mkdocs/src/doc/docs/images/mathjax_demo.png
diff --git a/mkdocs/src/doc/docs/images/mermaid_demo.png b/mkdocs/src/doc/docs/images/mermaid_demo.png
diff --git a/mkdocs/src/doc/docs/index.md b/mkdocs/src/doc/docs/index.md
@@ -1,38 +1,9 @@
 # Dokka 
 
-`Dokka` is an API documentation engine for `Kotlin` that performs the same function as the `Javadoc` tool for `Java`,
-but it's modern and highly pluggable.
+Dokka is an API documentation engine for Kotlin.
 
-Just like `Kotlin` itself, `Dokka` supports mixed-language projects (`Kotlin`/`Java`). It understands
-[KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in `Kotlin` source files as well
-as [Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#format) in `Java` 
-files, and can generate documentation in multiple formats including its own `HTML` format, Java's `Javadoc` lookalike
-and `Markdown`.
+If you want to learn how to use Dokka, see 
+[documentation on kotlinlang.org](https://kotlinlang.org/docs/dokka-introduction.html).
 
-Some libraries that use `Dokka` for API reference docs:
-
-* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/)
-* [kotlinx.serialization](https://kotlinlang.org/api/kotlinx.serialization/)
-* [Ktor](https://api.ktor.io/)
-* [Spring Framework](https://docs.spring.io/spring-framework/docs/current/kdoc-api/)
-
-___
-
-`Dokka` provides support for the following build systems:
-
-* [Gradle](user_guide/applying/gradle.md) (preferred)
-* [Maven](user_guide/applying/maven.md)
-* [Command line](user_guide/applying/cli.md)
-
-___
-
-`Dokka` is also very pluggable and comes with convenient plugin and extension point API. 
-
-You can write a plugin to support [mermaid.js](community/plugins-list.md#mermaid) diagrams,
-[mathjax](community/plugins-list.md#mathjax) formulas or even write custom processing of your own tags and annotations.
-
-For more info, see:
-
-* [Sample plugin tutorial](developer_guide/plugin-development/sample-plugin-tutorial.md)
-* [Community plugins](community/plugins-list.md)
-* [Developer guides](developer_guide/introduction.md)
+If you want to learn more about Dokka's internals and/or how to write Dokka plugins,
+see [Developer guides](developer_guide/introduction.md).