Refactor streampipes-maven-plugin to auto-generate docs

.github/workflows/extensions-docs.yml

@@ -0,0 +1,68 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: "build-extensions-docs-and-share-as-artifact"
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron:  "0 3 * * 6"  # runs every saturday at 03:00:00
+
+jobs:
+  extensions-docs-artifact-building:
+    runs-on: ubuntu-latest
+    steps:
+      - name: clone
+        uses: actions/checkout@v4
+
+      - name: create working branch & set GitHub config
+        run: |
+          git checkout -b build-extensions-docs-${{ github.run_id }}
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+          cache: 'maven'
+
+      - name: Build with Maven
+        run: mvn clean package
+
+      - name: Publish Extensions docs as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: streampipes-extensions-docs
+          path: |
+            streampipes-extensions/streampipes-extensions-all-jvm/target/docs/pe/
+          retention-days: 5
+
+      - name: Publish Extensions image assets as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: streampipes-extensions-docs-image-assets
+          path: |
+            streampipes-extensions/streampipes-extensions-all-jvm/target/docs/img/
+          retention-days: 5
+
+      - name: Publish Extensions sidebar
+        uses: actions/upload-artifact@v3
+        with:
+          name: streampipes-extensions-docs-sidebar
+          path: |
+            streampipes-extensions/streampipes-extensions-all-jvm/target/docs/sidebars.json
+          retention-days: 5

streampipes-extensions/streampipes-extensions-all-jvm/pom.xml

@@ -78,6 +78,29 @@
 
     <build>
         <plugins>
+            <plugin>
+                <groupId>org.apache.streampipes</groupId>
+                <artifactId>streampipes-maven-plugin</artifactId>
+                <version>0.93.0-SNAPSHOT</version>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.apache.rocketmq</groupId>
+                        <artifactId>rocketmq-client-java</artifactId>
+                        <version>5.0.2</version>
+                    </dependency>
+                </dependencies>
+                <configuration>
+                    <initClass>org.apache.streampipes.extensions.all.jvm.AllExtensionsInit</initClass>
+                </configuration>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>extract-docs</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-checkstyle-plugin</artifactId>

streampipes-maven-plugin/README.md

@@ -0,0 +1,88 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one or more
+  ~ contributor license agreements.  See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright ownership.
+  ~ The ASF licenses this file to You under the Apache License, Version 2.0
+  ~ (the "License"); you may not use this file except in compliance with
+  ~ the License.  You may obtain a copy of the License at
+  ~
+  ~    http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~
+  -->
+
+# Apache StreamPipes Maven Plugin
+
+## Description
+
+The Apache StreamPipes is an internal developer plugin which eases the generation of documentation for
+adapters and pipeline elements.
+
+The plugin generates documentation files which can be integrated into the UI.
+
+## Usage
+
+The streampipes-maven-plugin can either be started from the command line or embedded into a project's pom.
+
+### Prerequisites
+
+The plugin must be started from a module which contains an `Init` class which inherits `ExtensionsModelSubmitter`.
+By default, the goal runs in the `package` phase.
+
+### Command line
+
+```bash
+# Switch to a directory containing StreamPipes extensions and an Init class, e.g., streampipes-extensions-all-jvm
+
+mvn streampipes:extract-docs -DinitClass=org.apache.streampipes.extensions.all.jvm.AllExtensionsInit
+```
+
+### Inclusion in pom file
+
+```xml
+
+<plugin>
+    <groupId>org.apache.streampipes</groupId>
+    <artifactId>streampipes-maven-plugin</artifactId>
+    <version>0.93.0</version>
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.rocketmq</groupId>
+            <artifactId>rocketmq-client-java</artifactId>
+            <version>5.0.2</version>
+        </dependency>
+    </dependencies>
+    <configuration>
+        <initClass>org.apache.streampipes.extensions.all.jvm.AllExtensionsInit</initClass>
+    </configuration>
+    <executions>
+        <execution>
+            <phase>package</phase>
+            <goals>
+                <goal>extract-docs</goal>
+            </goals>
+        </execution>
+    </executions>
+</plugin>
+```
+
+* Replace the `version` with the current development version.
+* Replace the `initClass` with the module's init class.
+* The dependency to RocketMQ is only needed for modules containing the RocketMQ sink and can be omitted otherwise.
+
+## Output
+
+The plugin creates a new folder `docs` in the module's `target` directory.
+
+The folder includes:
+
+* An `img` folder which has a subdirectory for each extension (named by the `appId`) containing the icon.
+* A `pe` folder which has a subdirectory for each extension (named by the `appId`) containing the `documentation.md`
+  file, which has been rewritten to match the requirements of the Docusaurus Markdown parser.
+* An updated `sidebar.json` file containing the sidebar, which is downloaded from the `streampipes-website` repo on
+  branch `dev` and updated with the current set of extensions.

streampipes-maven-plugin/pom.xml

@@ -118,27 +118,19 @@
             <groupId>org.codehaus.plexus</groupId>
             <artifactId>plexus-utils</artifactId>
         </dependency>
-        <dependency>
-            <groupId>org.jboss.forge.roaster</groupId>
-            <artifactId>roaster-api</artifactId>
-        </dependency>
-        <dependency>
-            <groupId>org.jboss.forge.roaster</groupId>
-            <artifactId>roaster-jdt</artifactId>
-            <scope>runtime</scope>
-        </dependency>
         <dependency>
             <groupId>com.google.code.gson</groupId>
             <artifactId>gson</artifactId>
         </dependency>
-        <dependency>
-            <groupId>com.j2html</groupId>
-            <artifactId>j2html</artifactId>
-        </dependency>
         <dependency>
             <groupId>org.yaml</groupId>
             <artifactId>snakeyaml</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.apache.streampipes</groupId>
+            <artifactId>streampipes-service-extensions</artifactId>
+            <version>0.93.0-SNAPSHOT</version>
+        </dependency>
     </dependencies>
 
     <build>