add site documentation

deploy site on release

README.md

@@ -13,6 +13,8 @@ Opposed to the frontend-maven-plugin this plugin is intended for builds that adh
 than to npm conventions. It will generate the most basic files needed for npm, like `package.json` or `ts-config.json` 
 and assumes that transpiling typescript is part of the build. 
 
+A complete reference of all goals and parameters can be found [here](https://eitco.github.io/typescript-maven-plugin/plugin-info.html)
+
 # usage 
 
 Add the typescript-maven-plugin to your build, enabling extensions:
@@ -61,7 +63,7 @@ needed in a package, omitting build specific information.
 ## generate-sources
 
 In this phase first the `install-node-and-npm` goal from the [frontend maven plugin](https://github.com/eirslett/frontend-maven-plugin) is called.
-THis will install node and npm in the configured versions. No need to install it by yourself.
+This will install node and npm in the configured versions. No need to install it by yourself.
 After that this plugins `npm-install` goal is called which basically executes `npm install` 
 
 > 📘 Maven users, note that `npm install` is not like `mvn install`. It simply installs the projects dependencies, not 
@@ -71,8 +73,8 @@ After that this plugins `npm-install` goal is called which basically executes `n
 ## compile
 
 In this phase the `compile` goal is called, which in turn calls `npm run compile` executing a script generated into the 
-file `package.json` earlier. This will compile the typescript sources, which are assumed in `src/main/ts` and 
-`target/generated-sources/main/ts`.
+file `package.json` earlier - which simply consists of a call to `tsc` the typescript compiler. This will compile the 
+typescript sources, which are assumed in `src/main/ts` and `target/generated-sources/main/ts`.
 
 
 ## package
@@ -275,3 +277,4 @@ If you are using a different npm registry that the default registry you can conf
 In this example the plugin will add the commandline parameter `--registry=https://my.registry.io` to every npm call. 
 
 
+

pom.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
@@ -14,6 +15,12 @@
     <version>4.0.2-SNAPSHOT</version>
     <packaging>maven-plugin</packaging>
 
+    <description>
+        This maven plugin provides a build lifecycle for transpiling and packaging typescript code, which it does
+        building on top of the frontend maven plugin. It is intended for use in builds where there are java and
+        typescript sources that produce components that need to be the same version.
+    </description>
+
     <developers>
         <developer>
             <name>Jan Schwarz</name>
@@ -29,8 +36,8 @@
         <url>https://github.com/eitco/typescript-maven-plugin.git</url>
         <connection>scm:git:https://github.com/eitco/typescript-maven-plugin.git</connection>
         <developerConnection>scm:git:https://github.com/eitco/typescript-maven-plugin.git</developerConnection>
-      <tag>HEAD</tag>
-  </scm>
+        <tag>HEAD</tag>
+    </scm>
 
 
     <dependencies>
@@ -75,6 +82,9 @@
         <plugins>
             <plugin>
                 <artifactId>maven-release-plugin</artifactId>
+                <configuration>
+                    <goals>deploy site site:stage scm-publish:publish-scm</goals>
+                </configuration>
             </plugin>
             <plugin>
                 <artifactId>maven-resources-plugin</artifactId>
@@ -94,6 +104,21 @@
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>license-maven-plugin</artifactId>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-site-plugin</artifactId>
+                <version>3.12.1</version>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-scm-publish-plugin</artifactId>
+                <version>3.1.0</version>
+                <configuration>
+                    <pubScmUrl>scm:git:https://github.com/eitco/eitco.github.io.git</pubScmUrl>
+                    <scmBranch>main</scmBranch>
+                    <subDirectory>${artifactId}</subDirectory>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 
@@ -108,4 +133,22 @@
         </repository>
     </repositories>
 
+    <reporting>
+        <excludeDefaults>true</excludeDefaults>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-plugin-report-plugin</artifactId>
+                <version>3.13.1</version>
+            </plugin>
+        </plugins>
+    </reporting>
+
+    <distributionManagement>
+        <site>
+            <id>github</id>
+            <url>scm:git:https://github.com/eitco/eitco.github.io.git</url>
+        </site>
+    </distributionManagement>
+
 </project>

src/main/java/de/eitco/cicd/typescript/maven/plugin/AbstractNpmExecutionMojo.java

@@ -22,6 +22,9 @@ public abstract class AbstractNpmExecutionMojo extends AbstractTypescriptMojo {
     @Component
     private BuildContext buildContext;
 
+    /**
+     * This parameter specifies whether the command line option {@code verbose} should be given to any npm execution.
+     */
     @Parameter(defaultValue = "false", property = "typescript.verbose")
     private boolean verbose;
 

src/main/java/de/eitco/cicd/typescript/maven/plugin/AbstractTypescriptMojo.java

@@ -32,85 +32,150 @@ public abstract class AbstractTypescriptMojo extends AbstractFrontendMojo {
 
     public static final String PACKAGE_FILE_NAME = "package.json";
     public static final Pattern DISALLOWED_VERSION_CHARACTERS = Pattern.compile("[^A-Za-z0-9-.+]");
+
     /**
      * This parameter holds the name of a package json file that will be merged with the package configuration given by
      * the maven parameters
      */
     @Parameter(property = "typescript.default.package.json")
     protected File defaultValues = null;
 
+    /**
+     * This parameter specifies whether the typescript plugin goals should be executed or not.
+     */
     @Parameter(defaultValue = "false", property = "ts.skip")
     private boolean skip;
 
+    /**
+     * This parameter specifies a directory where distribution package should be compiled to and be packaged from.
+     */
     @Parameter(
         defaultValue = "${project.build.directory}/dist",
         required = false
     )
     protected File distributionDirectory;
 
+    /**
+     * This parameter specifies the name of the project. This is the unique name the generated package will
+     * be referenced with.
+     */
     @Parameter(
         defaultValue = "${project.artifactId}",
         property = "typescript.project.name"
     )
     protected String projectName;
 
+    /**
+     * This parameter specifies the version of the package deployed.
+     */
     @Parameter(
         defaultValue = "${project.version}",
         property = "typescript.project.version"
     )
     protected String projectVersion;
 
+    /**
+     * This parameter specifies the npm registry to load dependencies from. If left empty the default
+     * registry (https://registry.npmjs.org/) will be used.
+     */
     @Parameter(
         property = "npmRegistryURL",
         required = false,
         defaultValue = ""
     )
     protected String npmRegistryURL;
 
+    /**
+     * This parameter specifies the npm registry to publish the generated package to. If left empty,
+     * the value of {@code npmRegistryURL} will be used instead.
+     */
     @Parameter(
         property = "typescript.publish.registry.url",
         required = false,
         defaultValue = ""
     )
     protected String publishRegistryURL;
 
+    /**
+     * This parameter specifies the name of the file implementing the entry point to the package. Omit the
+     * file suffix.
+     */
     @Parameter(
         defaultValue = "import"
     )
     protected String typescriptEntryPoint;
 
+    /**
+     * This parameter specifies a list of npm dependencies to add to the package compiled.
+     */
     @Parameter
     private List<NpmDependency> dependencies = new ArrayList<>();
 
+    /**
+     * This parameter specifies a list of npm dependencies to add to the package compiled. The difference to
+     * the parameter {@code {@link #dependencies}} is that this property is intended as a list of default
+     * dependencies specified in a common super pom, so that individual projects may add their dependencies
+     * without overwriting the default dependencies
+     */
     @Parameter
     private List<NpmDependency> defaultDependencies = new ArrayList<>();
 
     private Map<String, NpmDependency> allDependencies;
 
+    /**
+     * This parameter specifies the compile options to the typescript compiler.
+     */
     @Parameter
     protected CompilerOptions compileOptions = new CompilerOptions();
 
+    /**
+     * This parameter specifies the compile options to the typescript compiler when compiling test sources.
+     * This options will be used when generating the {@code tsconfig.spec.json}, which will always derive from
+     * {@code tsconfig.json} generated from the {@code {@link #compileOptions compile options parameter}}.
+     */
     @Parameter
     protected CompilerOptions testCompileOptions = new CompilerOptions();
 
+
+    /**
+     * This parameter specifies the {@code angularCompilerOptions} element of the generated {@code tsconfig.json} file.
+     */
     @Parameter
     protected AngularCompilerOptions angularCompilerOptions = new AngularCompilerOptions();
 
+    /**
+     * This parameter specifies the location of the typescript source files to compile.
+     */
     @Parameter
     protected List<String> sources = List.of("src/main/ts/**.ts", "target/generated-sources/main/ts/**.ts");
 
+    /**
+     * This parameter specifies the sources to exclude from compiling.
+     */
     @Parameter
     protected  List<String> sourceExcludes = List.of();
 
+    /**
+     * This parameter specifies the location of the test source files.
+     */
     @Parameter
     protected List<String> testSources = List.of("src/test/ts/**.ts", "target/generated-sources/test/ts/**.ts");
 
+    /**
+     * This parameter specifies sources to exclude from test compiling.
+     */
     @Parameter
     protected List<String> testSourceExcludes = List.of();
 
+    /**
+     * This parameter specifies the typescript version
+     */
     @Parameter(property = "typescript.version", defaultValue = "4.6.2")
     protected String typeScriptVersion;
 
+    /**
+     * This parameter specifies a set of keywords to add to the projects {@code package.json} file.
+     */
     @Parameter
     protected List<String> keywords = new ArrayList<>();
 
@@ -131,14 +196,23 @@ public abstract class AbstractTypescriptMojo extends AbstractFrontendMojo {
 
     @Component
     protected ArtifactResolver artifactResolver;
+
     /**
-     * a suffix appended to the projects' version if and only if this version ends with "-SNAPSHOT"
+     * This parameter specifies a suffix appended to the projects' version if and only if this version ends with "-SNAPSHOT"
      */
     @Parameter(property = "typescript.snapshot.version.suffix")
     private String snapshotVersionSuffix;
+
+    /**
+     * This parameter specifies additional scripts to be written to the {@code package.json}. Those scripts can be
+     * executed using the frontend-maven-plugin.
+     */
     @Parameter
     private Map<String, String> additionalScripts = new LinkedHashMap<>();
 
+    /**
+     * This parameter specifies the name of a schematic to be added to the {@code package.json}.
+     */
     @Parameter
     private String schematics = null;
 

src/main/java/de/eitco/cicd/typescript/maven/plugin/DiffPackageMojo.java

@@ -12,6 +12,11 @@
 import java.io.File;
 import java.io.IOException;
 
+/**
+ * This goal compares the build configuration specified by the current project object model and compares it to the
+ * current {@code package.json} - any difference is written to the json file specified by {@code defaultValues} so that
+ * any other execution of different goals of the typescript-maven-plugin will honour those differences.
+ */
 @Mojo(name = "diff-package", threadSafe = true, defaultPhase = LifecyclePhase.GENERATE_SOURCES)
 public class DiffPackageMojo extends AbstractTypescriptMojo {
 

src/main/java/de/eitco/cicd/typescript/maven/plugin/GenerateNpmProjectMojo.java

@@ -20,6 +20,12 @@
 import java.io.IOException;
 
 
+/**
+ * This goal generates the files `package.json`, `ts-config.json`
+ * and `tsconfig.spec.json` from its configuration. It also generates a second `package.json` file inside the distribution
+ * directory. The second file will be the one distributed with the package. It contains only the basic project information
+ * needed in a package, omitting build specific information.
+ */
 @Mojo(name = "generate-project", threadSafe = true, defaultPhase = LifecyclePhase.INITIALIZE)
 public class GenerateNpmProjectMojo extends AbstractTypescriptMojo {
 

src/main/java/de/eitco/cicd/typescript/maven/plugin/InstallNpmMojo.java

@@ -11,12 +11,21 @@
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
 
+/**
+ * This goal basically executes {@code npm install}.
+ */
 @Mojo(name = "npm-install", threadSafe = true, defaultPhase = LifecyclePhase.GENERATE_RESOURCES)
 public class InstallNpmMojo extends AbstractNpmExecutionMojo {
 
+    /**
+     * This parameter specifies whether the {@code --force} command line option is set.
+     */
     @Parameter(defaultValue = "false", property = "typescript.install.force")
     private boolean force;
 
+    /**
+     * This parameter specifies whether the {@code --legacy-peer-deps} command line option is set.
+     */
     @Parameter(defaultValue = "false", property = "typescript.install.legacyPeerDeps")
     private boolean legacyPeerDeps;
 

src/main/java/de/eitco/cicd/typescript/maven/plugin/NpmCompileMojo.java

@@ -11,6 +11,10 @@
 import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 
+/**
+ * This goal compiles the typescript sources. It does so by calling the {@code compile} script, which in turn
+ * simply calls {@code tsc}.
+ */
 @Mojo(name = "compile", threadSafe = true, defaultPhase = LifecyclePhase.COMPILE)
 public class NpmCompileMojo extends AbstractNpmExecutionMojo {
     @Override

src/main/java/de/eitco/cicd/typescript/maven/plugin/NpmDeployMojo.java

@@ -11,6 +11,9 @@
 import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 
+/**
+ * This goal deploys the npm package by calling {@code npm publish}.
+ */
 @Mojo(name = "deploy", threadSafe = true, defaultPhase = LifecyclePhase.INSTALL)
 public class NpmDeployMojo extends DistributionDirectoryNpmExecutionMojo {
 

src/main/java/de/eitco/cicd/typescript/maven/plugin/NpmPackageMojo.java

@@ -32,6 +32,11 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
+/**
+ * This goal packages the npm package by calling {@code npm pack}. Additionally, this attaches
+ * the package created, the `package.json` file and the `package-lock.json` file to the project so
+ * that the maven default install and deploy plugins will install/deploy them.
+ */
 @Mojo(name = "package", threadSafe = true, defaultPhase = LifecyclePhase.PACKAGE)
 public class NpmPackageMojo extends DistributionDirectoryNpmExecutionMojo {