diff --git a/renderer/build.gradle.kts b/renderer/build.gradle.kts index f243e12..9e0c4bc 100644 --- a/renderer/build.gradle.kts +++ b/renderer/build.gradle.kts @@ -5,6 +5,10 @@ plugins { alias(opensavvyConventions.plugins.kotlin.abstractLibrary) } +java { + withSourcesJar() +} + kotlin { jvmToolchain(8) } -- 2.51.2 From 37ac70f5a61df6a6f85eb00bb574111c0e8114b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 12 Oct 2024 19:58:34 +0200 Subject: [PATCH 2/4] docs(website): Create the documentation website --- docs/website/docs/index.md | 10 +++++++++- docs/website/mkdocs.yml | 4 ++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/website/docs/index.md b/docs/website/docs/index.md index 4f5ca0b..0b8d593 100644 --- a/docs/website/docs/index.md +++ b/docs/website/docs/index.md @@ -4,4 +4,12 @@ template: home.html # Welcome! -The OpenSavvy Playground is a project template with pre-configured CI/CD, documentation generator, etc. +Dokka in Material for MkDocs is a Gradle plugin using Dokka to extract documentation comments (KDoc) and embed them in a generated website. + +- [**Get started**](setup.md) +- [**Visit the demo**](api/-library%20module/index.md) + +This plugin should work for any kind of project supported by Dokka: Kotlin/JVM, Kotlin/Multiplatform, etc. +This also includes extracting Java source comments from mixed Java/Kotlin projects. + +This project is very early in development. If you find something missing, or a stability issue, please [create an issue](https://gitlab.com/opensavvy/automation/dokka-material-mkdocs/-/issues/new) or [email us](mailto:contact-project+opensavvy-automation-dokka-material-mkdocs-60473792-issue-@incoming.gitlab.com). diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index d6817aa..842527a 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -1,7 +1,7 @@ -site_name: OpenSavvy Playground +site_name: Dokka in Material for MkDocs site_author: OpenSavvy & contributors site_description: > - Project template with CI/CD and IDE configuration. + Embed your Kotlin documentation comments into a Material for MkDocs site theme: name: material -- 2.51.2 From 05144726cb7f0fd69fa7e0bc4f0c45963b8c1fc2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 12 Oct 2024 19:59:04 +0200 Subject: [PATCH 3/4] docs(website): Create a configuration guide --- docs/website/docs/setup.md | 97 ++++++++++++++++++++++++++++++++++++++ docs/website/mkdocs.yml | 3 +- 2 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 docs/website/docs/setup.md diff --git a/docs/website/docs/setup.md b/docs/website/docs/setup.md new file mode 100644 index 0000000..7cb78aa --- /dev/null +++ b/docs/website/docs/setup.md @@ -0,0 +1,97 @@ +# Configuration + +This project takes the form of a Gradle plugin which extracts information using Dokkatoo then embeds it into a [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) site. + +## Creating the project + +First, you will need to create a Material for MkDocs site (or you may use an existing one) that is in the same repository as the Gradle build which you want to extract documentation from. + +We recommend putting the Material for MkDocs site in a child directory of the main Gradle build (`settings.gradle` or `settings.gradle.kts`), instead of putting it into the same directory. + +For example, you may have a setup similar to this: +```text +your-project/ + docs/ + docs/ + index.md + mkdocs.yml + src/ + main/java/… + build.gradle.kts + settings.gradle.kts +``` + +You will also need to configure [Dokkatoo](https://github.com/adamko-dev/dokkatoo) for your project. You can follow the official documentation and use any of the official formats to test your configuration (e.g. the HTML format). + +## Configuring Gradle + +Locate the `mkdocs.yml` file. In the same directory, create a `build.gradle.kts` file: +```kotlin title="build.gradle.kts in the same folder as mkdocs.yml" +id("dev.opensavvy.dokkatoo-mkdocs") version "VERSION HERE" //(1)! + +dependencies { + // Embeds the documentation from project :foo-bar + dokkatoo(project("foo-bar")) +} +``` + +1. Latest version:
All versions: [Release list](https://gitlab.com/opensavvy/automation/dokka-material-mkdocs/-/releases) + +Each Gradle project that you want to include in the website should be added to the `dependencies` block. +You may include as many projects as you want. + +Each project mentioned needs to be configured to generate documentation with Dokkatoo, see the Dokkatoo documentation for more information. If you can see the documentation from the project in another format (e.g. Dokkatoo HTML), it is configured properly. + +Projects that are not mentioned in the `dependencies` block do not need to be configured to use Dokkatoo. + +Don't forget to include the project you created into your Gradle build: +```kotlin title="Root settings.gradle.kts" +// Everything else… + +include("docs") // or whatever other path you used +``` + +## Configuring Material for MkDocs + +The Gradle plugin will generate Markdown files in `docs/api`. You should probably add this directory to `.gitignore`, as it will change quite often. + +Material for MkDocs requires that all pages are added to the `nav` section of the main `mkdocs.yml` file. It is not currently possible to generate entries in another file, so the Gradle plugin must edit the `mkdocs.yml` file itself. + +To decide where you want the plugins to generate files, you must add the following marker comments: +```yaml title="mkdocs.yml" +# Everything else… + +nav: + - Home: # your existing pages… + - index.md + - setup.md + + - Another: another.md # your existing pages… + +# !!! EMBEDDED DOKKA START, DO NOT COMMIT !!! # +# !!! EMBEDDED DOKKA END, DO NOT COMMIT !!! # + + - Whatever: whatever.md # your existing pages… +``` + +When ran, the Gradle plugin will insert all pages generated by Dokka between both marker comments, overwriting anything that was previously there. The rest of the file will not be modified. + +At the moment, this plugin is only able to generate pages at the top-level. + +## Running + +Once all this configuration is done, you may run the plugin to generate the website. Assuming you have configured your Material for MkDocs website in the `docs` folder, run: +```shell +./gradlew docs:embedDokkaIntoMkDocs +``` + +This will populate the `docs/api` folder with the classes, functions… extracted from the Kotlin and Java code of the imported projects, and will add each pages to the `mkdocs.yml` file. + +Once this is done, you may run and open your Material for MkDocs site in the same way you usually do. + +Additionally, if you want the site to update when you edit source code, add the [`--continuous` Gradle flag](https://docs.gradle.org/current/userguide/continuous_builds.html): +```shell +./gradlew docs:embedDokkaIntoMkDocs --continuous +``` + +That's it! Your project is now configured to embed Kotlin and Java documentation comments into a Material for MkDocs website. diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 842527a..ae06baa 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -86,7 +86,8 @@ use_directory_urls: false nav: - Home: index.md - - Getting started: [] + - Getting started: + - setup.md - Plugin reference: - reference.md -- 2.51.2 From 6790defc666617ed2c02ea0f8aad5f758a75dad5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 12 Oct 2024 20:09:50 +0200 Subject: [PATCH 4/4] docs(example): Improve the library module header --- docs/example/example-core/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/example/example-core/README.md b/docs/example/example-core/README.md index 4dbc7d5..45bc400 100644 --- a/docs/example/example-core/README.md +++ b/docs/example/example-core/README.md @@ -1,8 +1,8 @@ # Module Library module -This is a demonstration of how to use the Dokka format. +Welcome to Dokka in Material for MkDocs! -This text is written in a markdown file that is included in the library module. Dokka uses it to generate the module and package headers. +This page is the documentation header for the `example-core` module. It is declared using Dokka's `includes` functionality to use Markdown documents to describe modules and packages. In this file, you can include code: ```kotlin @@ -16,9 +16,11 @@ as well as other Markdown features, like quotes: Module pages can have subheaders to describe multiple sections of content. +The behavior is identical to Dokka's headers mechanisms. + # Package opensavvy.dokka.material.mkdocs.example This is the description of a package. The description may be arbitrary long, but only the first paragraph is displayed in the module page. -However, it is contained in its entirety in the package page. +Therefore, this sentence doesn't appear in the module page, but does appear in the paragraph page.