1 files changed, 41 insertions, 0 deletions
diff --git a/examples/gradle/dokka-library-publishing-example/README.md b/examples/gradle/dokka-library-publishing-example/README.md
new file mode 100644
index 00000000..60d967b8
--- /dev/null
+++ b/examples/gradle/dokka-library-publishing-example/README.md
@@ -0,0 +1,41 @@
+# Dokka Library publishing example
+
+This example demonstrates how you can integrate Dokka into the publishing process of your library, adding
+documentation generated by Dokka as artifacts.
+
+This is useful because some repositories, like Maven Central, require documentation (`javadoc.jar`) to be published
+alongside library artifacts.
+
+You can also use services like [javadoc.io](https://javadoc.io/) to host of your library's API documentation for free 
+and without any additional setup - it will take documentation pages straight from the published artifact. It works with 
+both HTML and Javadoc formats as demonstrated by 
+[com.trib3's Javadocs](https://javadoc.io/doc/com.trib3/server/latest/index.html).
+
+## Running
+
+Run `dokkaHtml` task to generate documentation for this example:
+
+```bash
+./gradlew dokkaHtml
+```
+
+### Javadoc jar
+
+Run `dokkaJavadocJar` task to create a jar file that contains documentation generated in Dokka's Javadoc format.
+
+```Bash
+./gradlew dokkaJavadocJar
+```
+
+After that, you can find the jar under `build/libs/dokka-library-publishing-example-javadoc.jar`
+
+### HTML jar
+
+
+Run `dokkaHtmlJar` task to create a jar file that contains documentation generated in Dokka's HTML format.
+
+```Bash
+./gradlew dokkaHtmlJar
+```
+
+After that, you can find the jar under `build/libs/dokka-library-publishing-example-html.jar`