SLING-9527 - Add a proper documentation page for the Scripting Bundle Maven Plugin
diff --git a/README.md b/README.md
index 304f1d9..882d7a4 100644
--- a/README.md
+++ b/README.md
@@ -13,104 +13,11 @@
Apache Sling Scripting Bundle Maven Plugin
====
-## What
-This plugin provides support for deriving `sling.resourceType` `Requirements` and `Capabilities` from
-the file-system layout of scripts. Bundles that get extended by the
-[`org.apache.sling.scripting.bundle.tracker`](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker) with these `Requirements` and
-`Capabilities` will have their scripts made available automatically with added versioning and dependency
-support.
+The Apache Sling Scripting Bundle Maven Plugin provides support for generating OSGi bundles
+that provide embedded or precompiled scripts to perform server-side rendering in an Apache
+Sling application. When executed, the plugin will define two project properties
+(`org.apache.sling.scriptingbundle.maven.plugin.Require-Capability` and
+`org.apache.sling.scriptingbundle.maven.plugin.Provide-Capability`) which can be used to
+populate the corresponding bundle headers.
-## Why
-Manually defining the `Require-Capability` and `Provide-Capability` bundle headers is error-prone and unnecessary,
-as they can be derived from the file-system layout required for scripts by the resolver (for the most part).
-
-## How
-The plugin scans the `javax.script` file-system directory and will generate `Capabilities` for the scripts it finds. It
-expects the following layout:
-
-```
-javax.script/<sling-resourceType>/<version>/[<METHOD>.]<name>[.<selector>][.<extension>].<script-extension>
-```
-
-From that, it will create an appropriate `Provide-Capability` (see the ["How"](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker/#how)
-section of the scripting bundle tracker) with the following extra assumptions:
-
- * if the `name` part equals the `sling.resourceType` or the last part of it, it is assumed to be the name of the main script;
- otherwise, it is assumed to be a selector;
- * if the file name is just `extends` it is assumed to be a file containing a single line with the
- `resourceType` used for the `extends` capability attribute followed by a `;version=<version-range>`; in this case, the
- plugin will set the `extends` attribute to the given `resourceType` and generate a `Require-Capability` for that
- `resourceType` with the given version range;
- * if the file name is just `requires` the plugin will read it line by line (assuming the same syntax as for the `extends` file)
- and generate a `Require-Capability` for each line based on the given `resourceType` and version range.
-
-### Example
-As an example, let's assume the following layout:
-
-```
-javax.scripting/
- org.foo/1.0.0
- POST.foo.html
-```
-
-This will generate following `Provide-Capability`:
-
-```
-sling.resourceType;
- sling.resourceType="org.foo";
- sling.servlet.methods:List<String>=POST;
- version:Version="1.0.0"
-```
-
-For a bigger example providing several versions and using an `extends` file consider the following two projects:
-
- * [example](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples/org-apache-sling-scripting-examplebundle);
- * [example.hi](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples/org-apache-sling-scripting-examplebundle.hi).
-
-## So how do I use the plugin?
-
-The plugin doesn't currently integrate with the `maven-bundle-plugin`. The generated `Require-Capability` and
-`Provide-Capability` headers values are simply made available via properties:
-
-```
-${org.apache.sling.scriptingbundle.maven.plugin.Provide-Capability}
-${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability}
-```
-
-However, that makes it reasonable straightforward to use the plugin by just adding it into your build in the
-`prepare-package` phase and use the two properties in the manifest writing instructions of another plugin like
-the `maven-bundle-plugin`:
-
-```
- <plugin>
- <groupId>org.apache.sling</groupId>
- <artifactId>scriptingbundle-maven-plugin</artifactId>
- <version>0.0.1-SNAPSHOT</version>
- <executions>
- <execution>
- <phase>prepare-package</phase>
- <goals>
- <goal>metadata</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Provide-Capability>
- ${org.apache.sling.scriptingbundle.maven.plugin.Provide-Capability}
- </Provide-Capability>
- <Require-Capability>
- osgi.extender;filter:="(&(osgi.extender=sling.scripting)(version>=1.0.0)(!(version>=2.0.0)))",
- ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability}
- </Require-Capability>
- </instructions>
- </configuration>
- </plugin>
-```
-
-You can find an example in [here](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples/org-apache-sling-scripting-examplebundle/pom.xml).
+For more details head over to the documentation page from https://sling.apache.org/components/scriptingbundle-maven-plugin/.
diff --git a/pom.xml b/pom.xml
index 7c23bb4..6782fd3 100644
--- a/pom.xml
+++ b/pom.xml
@@ -31,16 +31,28 @@
<version>0.1.1-SNAPSHOT</version>
<packaging>maven-plugin</packaging>
- <scm>
- <connection>scm:git:https://gitbox.apache.org/repos/asf/sling-scriptingbundle-maven-plugin.git</connection>
- <developerConnection>scm:git:https://gitbox.apache.org/repos/asf/sling-scriptingbundle-maven-plugin.git</developerConnection>
- <url>https://gitbox.apache.org/repos/asf?p=sling-scriptingbundle-maven-plugin.git</url>
- <tag>HEAD</tag>
- </scm>
+ <name>Apache Sling Scripting Bundle Maven Plugin</name>
+ <description>The Apache Sling Scripting Bundle Maven Plugin provides support for packing server-side scripts as bundle
+ entries (directly embedded or compiled as Java classes). When executed, the plugin will define two system properties
+ which can be used to populate the Provide-Capability and Require-Capability bundle headers.</description>
+ <url>https://sling.apache.org/components/scriptingbundle-maven-plugin/</url>
+
+ <scm>
+ <connection>scm:git:https://gitbox.apache.org/repos/asf/sling-scriptingbundle-maven-plugin.git</connection>
+ <developerConnection>scm:git:https://gitbox.apache.org/repos/asf/sling-scriptingbundle-maven-plugin.git</developerConnection>
+ <url>https://gitbox.apache.org/repos/asf?p=sling-scriptingbundle-maven-plugin.git</url>
+ <tag>HEAD</tag>
+ </scm>
+
+ <prerequisites>
+ <maven>${maven.version}</maven>
+ </prerequisites>
<properties>
<sling.java.version>8</sling.java.version>
<maven.version>3.6.0</maven.version>
+ <site.jira.version.id>12344664,12347157</site.jira.version.id>
+ <maven.site.path>${project.artifactId}-archives/${project.artifactId}-LATEST</maven.site.path>
</properties>
<build>
@@ -222,4 +234,24 @@
<scope>test</scope>
</dependency>
</dependencies>
+
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-plugin-plugin</artifactId>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-changes-plugin</artifactId>
+ <configuration>
+ <useJql>true</useJql>
+ <sortColumnNames>resolutiondate DESC</sortColumnNames>
+ <columnNames>Type,Key,Summary,Fix Version</columnNames>
+ <resolutionIds>Fixed</resolutionIds>
+ </configuration>
+ </plugin>
+ </plugins>
+ </reporting>
+
</project>
diff --git a/src/main/java/org/apache/sling/scriptingbundle/maven/plugin/MetadataMojo.java b/src/main/java/org/apache/sling/scriptingbundle/maven/plugin/MetadataMojo.java
index d8ed20d..fb71657 100644
--- a/src/main/java/org/apache/sling/scriptingbundle/maven/plugin/MetadataMojo.java
+++ b/src/main/java/org/apache/sling/scriptingbundle/maven/plugin/MetadataMojo.java
@@ -60,7 +60,7 @@
* corresponding OSGi bundle headers for bundles providing scripts executable by a {@link javax.script.ScriptEngine}.
*/
@Mojo(name = "metadata",
- defaultPhase = LifecyclePhase.PACKAGE)
+ defaultPhase = LifecyclePhase.PREPARE_PACKAGE)
public class MetadataMojo extends AbstractMojo {
@Parameter(defaultValue = "${project}", readonly = true, required = true)
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 0000000..9f69bc1
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -0,0 +1,39 @@
+The Apache Sling Scripting Bundle Maven Plugin provides support for generating OSGi bundles
+that provide embedded or precompiled scripts to perform server-side rendering in an Apache
+Sling application. When executed, the plugin will define two project properties
+(`org.apache.sling.scriptingbundle.maven.plugin.Require-Capability` and
+`org.apache.sling.scriptingbundle.maven.plugin.Provide-Capability`) which can be used to
+populate the corresponding bundle headers.
+
+Bundles that get extended by the
+[`org.apache.sling.servlets.resolver`](https://github.com/apache/sling-org-apache-sling-servlets-resolver)
+with these `Requirements` and`Capabilities` will have their scripts made available automatically with added
+versioning and dependency support.
+
+Manually defining the `Require-Capability` and `Provide-Capability` bundle headers is error-prone and unnecessary,
+as they can be derived from the file-system layout required for scripts by the resolver (for the most part).
+
+## Goals
+The Scripting Bundle Maven Plugin has only one goal:
+
+* [scriptingbundle:metadata](metadata-mojo.html) is bound to the package phase and is used
+to generate the above mentioned project properties.
+
+
+## Usage
+General instructions on how to use the Scripting Bundle Maven Plugin can be found on the
+[usage](usage.html) page.
+
+In case you still have questions regarding the plugin's usage feel free to contact the
+Apache Sling Development List. The posts to the mailing list are archived and could
+already contain the answer to your question as part of an older thread. Hence, it is also
+worth browsing/searching the mail archive.
+
+If you feel like the plugin is missing a feature or has a defect, you can fill a feature
+request or bug report in our issue tracker. When creating a new issue, please provide a
+comprehensive description of your concern. Especially for fixing bugs it is crucial that the
+developers can reproduce your problem. For this reason, entire debug logs, POMs or most
+preferably little demo projects attached to the issue are very much appreciated. Of course,
+patches are welcome, too. Contributors can check out the project from our source repository
+and will find supplementary information in the Maven guide.
+
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
new file mode 100644
index 0000000..30e0f58
--- /dev/null
+++ b/src/site/markdown/usage.md.vm
@@ -0,0 +1,94 @@
+#set($h1 = '#')
+#set($h2 = '##')
+#set($h3 = '###')
+#set($h4 = '####')
+
+
+$h2 Usage
+
+The Scripting Bundle Maven Plugin will look for scripts in two project directories:
+
+ 1. `src/main/scripts` - this folder will contain scripts that will be pre-compiled
+ 2. `src/main/resources/javax.script` - this folder will contain scripts that will be embedded as is
+
+The structure in these source directories should then follow the normal way of structuring scripts in an Apache Sling application. For more
+details, check the [URL to Script Resolution](https://sling.apache.org/documentation/the-sling-engine/url-to-script-resolution.html#script-locations)
+page. In addition to the normal way of structuring scripts in the file tree, the plugin provides some additional features:
+
+ 1. Resource Type Versioning<br/>
+ This works by putting the scripts in a folder that follows this simple naming convention: `<resourceType>/<version>/`. The `<version>`
+ should be a valid semantic version (e.g. `1.0.0`)
+
+ 2. Defining explicit extends relationships (similar to the `sling:resourceSuperType` property)<br/>
+ An `extends` file in the resource type folder (versioned or not) allows defining this explicit relationship. This file must contain a
+ single line with the `resourceType` used for the `extends` capability attribute followed by a `;version=<version-range>`; in this
+ case, the plugin will set the `extends` attribute to the given `resourceType` and generate a `Require-Capability` for that
+ `resourceType` with the given version range.
+
+ 3. Defining an explicit requirement, without an inheritance relationship (e.g. delegation to another resource type)<br/>
+ A `requires` file (assuming the same conventions and syntax as for the `extends` file) will generate a `Require-Capability` for each
+ line based on the given `resourceType` and version range.
+
+$h3 Defining scripts
+As an example, let's assume the following layout:
+```
+src/main/resources/javax.script/
+ org.foo/1.0.0
+ foo.POST.html
+```
+
+This will generate following `Provide-Capability`:
+
+```
+sling.servlet;
+ sling.servlet.resourceTypes:List<String>="org.foo";
+ sling.servlet.methods:List<String>=POST;
+ version:Version="1.0.0"
+```
+
+For more complex examples head over to https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples.
+
+$h3 So how do I use the plugin?
+The plugin doesn't currently integrate with the `maven-bundle-plugin`, nor the `bnd-maven-plugin`. However, the generated
+`Require-Capability` and `Provide-Capability` headers values are simply made available via properties:
+
+```
+${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability}
+${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability}
+```
+
+That makes it reasonable straightforward to use the plugin by just adding it into your build in the
+`prepare-package` phase and use the two properties in the manifest writing instructions of another plugin like
+the `maven-bundle-plugin`:
+
+```
+<plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <phase>prepare-package</phase>
+ <goals>
+ <goal>metadata</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+<plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <Provide-Capability>
+ ${org.apache.sling.scriptingbundle.maven.plugin.Provide-Capability}
+ </Provide-Capability>
+ <Require-Capability>
+ osgi.extender;filter:="(&(osgi.extender=sling.scripting)(version>=1.0.0)(!(version>=2.0.0)))",
+ ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability}
+ </Require-Capability>
+ </instructions>
+ </configuration>
+</plugin>
+```
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 0000000..2592253
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+<project>
+ <skin>
+ <groupId>org.apache.maven.skins</groupId>
+ <artifactId>maven-fluido-skin</artifactId>
+ <version>1.6</version>
+ </skin>
+ <body>
+ <menu name="Overview">
+ <item name="Introduction" href="index.html"/>
+ <item name="Goals" href="plugin-info.html"/>
+ <item name="Usage" href="usage.html"/>
+ </menu>
+ <menu ref="reports"/>
+ </body>
+ <custom>
+ <fluidoSkin>
+ <sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
+ </fluidoSkin>
+ </custom>
+</project>
