From 0a944ce05c4f2d4c175e2ab30d82f423e537dc28 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> Date: Mon, 26 Aug 2024 12:50:01 +0200 Subject: [PATCH] docs: add chapter about autodoc (#201) --- developer/autodoc.md | 34 +--- developer/wip/for-contributors/autodoc.md | 158 ++++++++++++++++++ .../for-contributors/contributor-handbook.md | 23 +++ .../control-plane/extension-model.md | 2 +- 4 files changed, 183 insertions(+), 34 deletions(-) create mode 100644 developer/wip/for-contributors/autodoc.md diff --git a/developer/autodoc.md b/developer/autodoc.md index a5cfba13..83c8c71a 100644 --- a/developer/autodoc.md +++ b/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:::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//control-plane-core-0.1.4-SNAPSHOT-manifest.json` +the contents of this file have been moved [here](./wip/for-contributors/autodoc.md) \ No newline at end of file diff --git a/developer/wip/for-contributors/autodoc.md b/developer/wip/for-contributors/autodoc.md new file mode 100644 index 00000000..d58686eb --- /dev/null +++ b/developer/wip/for-contributors/autodoc.md @@ -0,0 +1,158 @@ +# The `autodoc` Gradle plugin + + +* [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) + + +## 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:>") + } +} + ``` + +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 { + processorVersion.set("") + } + ``` + **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 `/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 { + 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 { + 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 `/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:::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//control-plane-core-0.4.2-SNAPSHOT-manifest.json` + diff --git a/developer/wip/for-contributors/contributor-handbook.md b/developer/wip/for-contributors/contributor-handbook.md index fa59b947..0d4063e0 100644 --- a/developer/wip/for-contributors/contributor-handbook.md +++ b/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 diff --git a/developer/wip/for-contributors/control-plane/extension-model.md b/developer/wip/for-contributors/control-plane/extension-model.md index 31e69ca0..0704575f 100644 --- a/developer/wip/for-contributors/control-plane/extension-model.md +++ b/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