docs: add chapter about autodoc (#201)

developer/autodoc.md

@@ -1,33 +1 @@
-# The `autodoc` Gradle plugin
-
-Please find the comprehensive documentation about the `autodoc` plugin in
-the [GitHub Repo](https://github.com/eclipse-edc/GradlePlugins/blob/main/docs/developer/autodoc.md) of
-the plugin.
-
-In EDC, the plugin is intended to be used to generate metamodel manifests for every Gradle module, which then
-transformed into Markdown files, subsequently rendered for publication in static web content.
-
-## Publishing the manifest files
-
-For every subproject that generates an `edc.json` file a Maven publication is created in the root build file, so that
-the manifest file gets published alongside the binary jar files, sources jar and javadoc jar.
-
-## Downloading the manifest files
-
-For publishing we use `type=json` and `classifier=manifest`, which means a dependency in a client project would look
-like
-this (kotlin DSL):
-
-```kotlin
-implementation("org.eclipse.edc:<ARTIFACT>:<VERSION>:manifest@json")
-```
-
-For example, for the `:core:control-plane:control-plane-core` module in version `0.1.4-SNAPSHOT`, this would be:
-
-```kotlin
-implementation("org.eclipse.edc:control-plane-core:0.1.4-SNAPSHOT:manifest@json")
-```
-
-When the dependency gets resolved, the manifest file will get downloaded to the local gradle cache, typically located
-at `.gradle/caches/modules-2/files-2.1`. So in the example the manifest would get downloaded
-at `~/.gradle/caches/modules-2/files-2.1/org.eclipse.edc/control-plane-core/0.1.4-SNAPSHOT/<HASH>/control-plane-core-0.1.4-SNAPSHOT-manifest.json`
+the contents of this file have been moved [here](./wip/for-contributors/autodoc.md)

developer/wip/for-contributors/autodoc.md

@@ -0,0 +1,158 @@
+# The `autodoc` Gradle plugin
+
+<!-- TOC -->
+* [The `autodoc` Gradle plugin](#the-autodoc-gradle-plugin)
+  * [1. Introduction](#1-introduction)
+  * [2. Module structure](#2-module-structure)
+  * [3. Usage](#3-usage)
+    * [3.1 Add the plugin to the `buildscript` block of your `build.gradle.kts`:](#31-add-the-plugin-to-the-buildscript-block-of-your-buildgradlekts)
+    * [3.2 Apply the plugin to the project:](#32-apply-the-plugin-to-the-project)
+    * [3.3 Configure the plugin [optional]](#33-configure-the-plugin-optional)
+  * [4. Merging the manifests](#4-merging-the-manifests)
+  * [5. Using published manifest files (MavenCentral)](#5-using-published-manifest-files-mavencentral)
+<!-- TOC -->
+
+## 1. Introduction
+
+In EDC, the autodoc plugin is intended to be used to generate metamodel manifests for every Gradle module, which can
+then transformed into Markdown or HTML files, and subsequently be rendered for publication in static web content.
+
+The plugin code can be found in the [GradlePlugins GitHub Repository](https://github.com/eclipse-edc/GradlePlugins).
+
+The `autodoc` plugin hooks into the Java compiler task (`compileJava`) and generates a module manifest file that
+contains meta information about each module. For example, it exposes all required and provided dependencies of an EDC
+`ServiceExtension`.
+
+## 2. Module structure
+
+The `autodoc` plugin is located at `plugins/autodoc` and consists of four separate modules:
+
+- `autodoc-plugin`: contains the actual Gradle `Plugin` and an `Extension` to configure the plugin. This module is
+  published to MavenCentral.
+- `autodoc-processor`: contains an `AnnotationProcessor` that hooks into the compilation process and builds the manifest
+  file. Published to MavenCentral.
+- `autodoc-converters`: used to convert JSON manifests to Markdown or HTML
+
+## 3. Usage
+
+In order to use the `autodoc` plugin we must follow a few simple steps. All examples use the Kotlin DSL.
+
+### 3.1 Add the plugin to the `buildscript` block of your `build.gradle.kts`:
+
+   ```kotlin
+   buildscript {
+    repositories {
+        maven {
+            url = uri("https://oss.sonatype.org/content/repositories/snapshots/")
+        }
+    }
+    dependencies {
+        classpath("org.eclipse.edc.autodoc:org.eclipse.edc.autodoc.gradle.plugin:<VERSION>>")
+    }
+}
+   ```
+
+Please note that the `repositories` configuration can be omitted, if the release version of the plugin is used.
+
+### 3.2 Apply the plugin to the project:
+
+There are two options to apply a plugin. For multi-module builds this should be done at the root level.
+
+1. via `plugin` block:
+   ```kotlin
+   plugins {
+       id("org.eclipse.edc.autodoc")
+   }
+   ```
+2. using the iterative approach, useful when applying to `allprojects` or `subprojects`:
+   ```kotlin
+   subprojects{
+      apply(plugin = "org.eclipse.edc.autodoc")
+   }
+   ```
+
+### 3.3 Configure the plugin [optional]
+
+The `autodoc` plugin exposes the following configuration values:
+
+1. the `processorVersion`: tells the plugin, which version of the annotation processor module to use. Set this value if
+   the version of the plugin and of the annotation processor diverge. If this is omitted, the plugin will use its own
+   version. Please enter _just_ the SemVer-compliant version string, no `groupId` or `artifactName` are needed.
+   ```kotlin
+   configure<org.eclipse.edc.plugins.autodoc.AutodocExtension> {
+       processorVersion.set("<VERSION>")
+   }
+   ```
+   **Typically, you do not need to configure this and can safely omit it.**
+
+_The plugin will then generate an `edc.json` file for every module/gradle project._
+
+## 4. Merging the manifests
+
+There is a Gradle task readily available to merge all the manifests into one large `manifest.json` file. This comes in
+handy when the JSON manifest is to be converted into other formats, such as Markdown, HTML, etc.
+
+To do that, execute the following command on a shell:
+
+```bash
+./gradlew mergeManifest
+```
+
+By default, the merged manifests are saved to `<rootProject>/build/manifest.json`. This destination file can be
+configured using a task property:
+
+```kotlin
+    // delete the merged manifest before the first merge task runs
+tasks.withType<MergeManifestsTask> {
+    destinationFile = YOUR_MANIFEST_FILE
+}
+```
+
+Be aware that due to the multithreaded nature of the merger task, every subproject's `edc.json` gets appended to the
+destination file, so it is a good idea to delete that file before running the `mergeManifest` task. Gradle can take care
+of that for you though:
+
+```kotlin
+// delete the merged manifest before the first merge task runs
+rootProject.tasks.withType<MergeManifestsTask> {
+    doFirst { YOUR_MANIFEST_FILE.delete() }
+}
+```
+
+## 5. Rendering manifest files as Markdown or HTML
+
+Manifests get created as JSON, which may not be ideal for end-user consumption. To convert them to HTML or Markdown,
+execute the following Gradle task:  
+
+```shell
+./gradlew doc2md # or doc2html
+```
+
+this looks for manifest files and convert them all to either Markdown (`doc2md`) or static HTML (`doc2html`). Note that
+if merged the manifests before (`mergeManifests`), then the merged manifest file gets converted too.
+
+The resulting `*.md` or `*.html` files are located next to the `edc.json` file in `<module-path>/build/`.
+
+## 6. Using published manifest files (MavenCentral)
+
+Manifest files (`edc.json`) are published alongside the binary jar files, sources jar and javadoc jar to MavenCentral
+for easy consumption by client projects. The manifest is published using `type=json` and `classifier=manifest`
+properties. 
+
+Client projects that want to download manifest files (e.g. for rendering static web content), simply define a Gradle
+dependency like this (kotlin DSL):
+
+```kotlin
+implementation("org.eclipse.edc:<ARTIFACT>:<VERSION>:manifest@json")
+```
+
+For example, for the `:core:control-plane:control-plane-core` module in version `0.4.2-SNAPSHOT`, this would be:
+
+```kotlin
+implementation("org.eclipse.edc:control-plane-core:0.4.2-SNAPSHOT:manifest@json")
+```
+
+When the dependency gets resolved, the manifest file will get downloaded to the local gradle cache, typically located at
+`.gradle/caches/modules-2/files-2.1`. So in the example the manifest would get downloaded at
+`~/.gradle/caches/modules-2/files-2.1/org.eclipse.edc/control-plane-core/0.4.2-SNAPSHOT/<HASH>/control-plane-core-0.4.2-SNAPSHOT-manifest.json`
+

developer/wip/for-contributors/contributor-handbook.md

@@ -233,4 +233,27 @@ Please find general best practices and recommendations [here](./best-practices.m
 
 ### 6.2 Autodoc
 
+In EDC there is an automated way to generate basic documentation about extensions, plug points, SPI modules and
+configuration settings. To achieve this, simply annotate respective elements directly in Java code:
+
+```java
+@Extension(value = "Some supercool extension", categories = {"category1", "category2"})
+public class SomeSupercoolExtension implements ServiceExtension {
+
+  // default value -> not required
+  @Setting(value = "Some string config property", type = "string", defaultValue = "foobar", required = false)
+  public static final String SOME_STRING_CONFIG_PROPERTY = "edc.some.supercool.string";
+
+  //no default value -> required
+  @Setting(value = "Some numeric config", type = "integer", required = true)
+  public static final String SOME_INT_CONFIG_PROPERTY = "edc.some.supercool.int";
+
+  // ...
+}
+```
+
+during compilation, the EDC build plugin generates documentation for each module as structured JSON.
+
+Detailed information about autodoc can be found [here](./autodoc.md)
+
 ### 6.3 Adapting the Gradle build

developer/wip/for-contributors/control-plane/extension-model.md

@@ -96,7 +96,7 @@ the extension, for example:
 
 To achieve this, the [EDC Runtime Metamodel](https://github.com/eclipse-edc/Runtime-Metamodel) defines several
 annotations. These are not required for compilation, but they should be added to the appropriate classes and fields with
-proper attributes to enable good documentation.
+proper attributes to enable good documentation. For detailed information please read [this chapter](../contributor-handbook.md#62-autodoc).
 
 Note that `@Provider`, `@Inject`, `@Provides` and `@Requires` are used by Autodoc to resolve the dependency graph for
 documentation, but they are also used by the runtime to resolve service dependencies. Read more about that