Add support for configuring the documentation output file name

siddhi-io · Jul 1, 2017 · c9caa14 · c9caa14
1 parent af450f9
commit c9caa14
Show file tree

Hide file tree

Showing 13 changed files with 145 additions and 118 deletions.
diff --git a/findbugs-exclude.xml b/findbugs-exclude.xml
@@ -160,20 +160,4 @@
     <Match>
         <Package name="~org\.wso2\.siddhi\.sample.*"/>
     </Match>
-    <Match>
-        <Class name="org.wso2.siddhi.doc.gen.commons.ExtensionMetaData"/>
-        <Bug pattern="EI_EXPOSE_REP, EI_EXPOSE_REP2"/>
-    </Match>
-    <Match>
-        <Class name="org.wso2.siddhi.doc.gen.commons.ParameterMetaData"/>
-        <Bug pattern="EI_EXPOSE_REP, EI_EXPOSE_REP2"/>
-    </Match>
-    <Match>
-        <Class name="org.wso2.siddhi.doc.gen.commons.ReturnAttributeMetaData"/>
-        <Bug pattern="EI_EXPOSE_REP, EI_EXPOSE_REP2"/>
-    </Match>
-    <Match>
-        <Class name="org.wso2.siddhi.doc.gen.commons.SystemParameterMetaData"/>
-        <Bug pattern="EI_EXPOSE_REP, EI_EXPOSE_REP2"/>
-    </Match>
 </FindBugsFilter>
diff --git a/modules/siddhi-core/siddhi-core-doc-gen/pom.xml b/modules/siddhi-core/siddhi-core-doc-gen/pom.xml
@@ -16,7 +16,8 @@
   ~ specific language governing permissions and limitations
   ~ under the License.
   -->
-<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:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
         <artifactId>siddhi</artifactId>
         <groupId>org.wso2.siddhi</groupId>
@@ -35,13 +36,14 @@
                 <executions>
                     <execution>
                         <goals>
-                            <goal>generate</goal>
+                            <goal>generate-md-docs</goal>
                         </goals>
                     </execution>
                 </executions>
                 <configuration>
                     <moduleTargetDirectory>../target/</moduleTargetDirectory>
                     <docGenDirectory>../../../docs/</docGenDirectory>
+                    <docGenFileName>documentation</docGenFileName>
                 </configuration>
             </plugin>
         </plugins>

diff --git a/modules/siddhi-doc-gen/pom.xml b/modules/siddhi-doc-gen/pom.xml
@@ -16,7 +16,8 @@
   ~ specific language governing permissions and limitations
   ~ under the License.
   -->
-<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:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
         <artifactId>siddhi</artifactId>
         <groupId>org.wso2.siddhi</groupId>

diff --git a/...ddhi/doc/gen/commons/ExampleMetaData.java → ...gen/commons/metadata/ExampleMetaData.java b/...ddhi/doc/gen/commons/ExampleMetaData.java → ...gen/commons/metadata/ExampleMetaData.java
@@ -15,7 +15,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.wso2.siddhi.doc.gen.commons;
+package org.wso2.siddhi.doc.gen.commons.metadata;
 
 /**
  * POJO for holding example meta data

diff --git a/...hi/doc/gen/commons/ExtensionMetaData.java → ...n/commons/metadata/ExtensionMetaData.java b/...hi/doc/gen/commons/ExtensionMetaData.java → ...n/commons/metadata/ExtensionMetaData.java
@@ -15,7 +15,9 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.wso2.siddhi.doc.gen.commons;
+package org.wso2.siddhi.doc.gen.commons.metadata;
+
+import java.util.List;
 
 /**
  * POJO for holding extension meta data
@@ -24,10 +26,10 @@ public class ExtensionMetaData {
     private String name;
     private String namespace;
     private String description;
-    private ParameterMetaData[] parameters;
-    private SystemParameterMetaData[] systemParameters;
-    private ReturnAttributeMetaData[] returnAttributes;
-    private ExampleMetaData[] examples;
+    private List<ParameterMetaData> parameters;
+    private List<SystemParameterMetaData> systemParameters;
+    private List<ReturnAttributeMetaData> returnAttributes;
+    private List<ExampleMetaData> examples;
 
     public String getName() {
         return name;
@@ -53,35 +55,35 @@ public void setDescription(String description) {
         this.description = description;
     }
 
-    public ParameterMetaData[] getParameters() {
+    public List<ParameterMetaData> getParameters() {
         return parameters;
     }
 
-    public void setParameters(ParameterMetaData[] parameters) {
+    public void setParameters(List<ParameterMetaData> parameters) {
         this.parameters = parameters;
     }
 
-    public SystemParameterMetaData[] getSystemParameters() {
+    public List<SystemParameterMetaData> getSystemParameters() {
         return systemParameters;
     }
 
-    public void setSystemParameters(SystemParameterMetaData[] systemParameters) {
+    public void setSystemParameters(List<SystemParameterMetaData> systemParameters) {
         this.systemParameters = systemParameters;
     }
 
-    public ReturnAttributeMetaData[] getReturnAttributes() {
+    public List<ReturnAttributeMetaData> getReturnAttributes() {
         return returnAttributes;
     }
 
-    public void setReturnAttributes(ReturnAttributeMetaData[] returnAttributes) {
+    public void setReturnAttributes(List<ReturnAttributeMetaData> returnAttributes) {
         this.returnAttributes = returnAttributes;
     }
 
-    public ExampleMetaData[] getExamples() {
+    public List<ExampleMetaData> getExamples() {
         return examples;
     }
 
-    public void setExamples(ExampleMetaData[] examples) {
+    public void setExamples(List<ExampleMetaData> examples) {
         this.examples = examples;
     }
 }
diff --git a/...siddhi/doc/gen/commons/ExtensionType.java → ...c/gen/commons/metadata/ExtensionType.java b/...siddhi/doc/gen/commons/ExtensionType.java → ...c/gen/commons/metadata/ExtensionType.java
@@ -15,7 +15,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.wso2.siddhi.doc.gen.commons;
+package org.wso2.siddhi.doc.gen.commons.metadata;
 
 /**
  * Enum for holding extension types supported by the doc generator

diff --git a/...hi/doc/gen/commons/NamespaceMetaData.java → ...n/commons/metadata/NamespaceMetaData.java b/...hi/doc/gen/commons/NamespaceMetaData.java → ...n/commons/metadata/NamespaceMetaData.java
@@ -15,7 +15,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.wso2.siddhi.doc.gen.commons;
+package org.wso2.siddhi.doc.gen.commons.metadata;
 
 import java.util.List;
 import java.util.Map;

diff --git a/...hi/doc/gen/commons/ParameterMetaData.java → ...n/commons/metadata/ParameterMetaData.java b/...hi/doc/gen/commons/ParameterMetaData.java → ...n/commons/metadata/ParameterMetaData.java
@@ -15,16 +15,18 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.wso2.siddhi.doc.gen.commons;
+package org.wso2.siddhi.doc.gen.commons.metadata;
 
 import org.wso2.siddhi.annotation.util.DataType;
 
+import java.util.List;
+
 /**
  * POJO for holding extension parameter meta data
  */
 public class ParameterMetaData {
     private String name;
-    private DataType[] type;
+    private List<DataType> type;
     private String description;
     private boolean optional;
     private boolean dynamic;
@@ -38,11 +40,11 @@ public void setName(String name) {
         this.name = name;
     }
 
-    public DataType[] getType() {
+    public List<DataType> getType() {
         return type;
     }
 
-    public void setType(DataType[] type) {
+    public void setType(List<DataType> type) {
         this.type = type;
     }
 

diff --git a/.../gen/commons/ReturnAttributeMetaData.java → ...ons/metadata/ReturnAttributeMetaData.java b/.../gen/commons/ReturnAttributeMetaData.java → ...ons/metadata/ReturnAttributeMetaData.java
@@ -15,16 +15,18 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.wso2.siddhi.doc.gen.commons;
+package org.wso2.siddhi.doc.gen.commons.metadata;
 
 import org.wso2.siddhi.annotation.util.DataType;
 
+import java.util.List;
+
 /**
  * POJO for holding extension return attribute meta data
  */
 public class ReturnAttributeMetaData {
     private String name;
-    private DataType[] type;
+    private List<DataType> type;
     private String description;
 
     public String getName() {
@@ -35,11 +37,11 @@ public void setName(String name) {
         this.name = name;
     }
 
-    public DataType[] getType() {
+    public List<DataType> getType() {
         return type;
     }
 
-    public void setType(DataType[] type) {
+    public void setType(List<DataType> type) {
         this.type = type;
     }
 

diff --git a/.../gen/commons/SystemParameterMetaData.java → ...ons/metadata/SystemParameterMetaData.java b/.../gen/commons/SystemParameterMetaData.java → ...ons/metadata/SystemParameterMetaData.java
@@ -15,7 +15,9 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.wso2.siddhi.doc.gen.commons;
+package org.wso2.siddhi.doc.gen.commons.metadata;
+
+import java.util.List;
 
 /**
  * POJO for holding extension system parameters meta data
@@ -24,7 +26,7 @@ public class SystemParameterMetaData {
     private String name;
     private String description;
     private String defaultValue;
-    private String[] possibleParameters;
+    private List<String> possibleParameters;
 
     public String getName() {
         return name;
@@ -50,11 +52,11 @@ public void setDefaultValue(String defaultValue) {
         this.defaultValue = defaultValue;
     }
 
-    public String[] getPossibleParameters() {
+    public List<String> getPossibleParameters() {
         return possibleParameters;
     }
 
-    public void setPossibleParameters(String[] possibleParameters) {
+    public void setPossibleParameters(List<String> possibleParameters) {
         this.possibleParameters = possibleParameters;
     }
 }
diff --git a/...iddhi-doc-gen/src/main/java/org/wso2/siddhi/doc/gen/core/DocumentationGenerationMojo.java b/...iddhi-doc-gen/src/main/java/org/wso2/siddhi/doc/gen/core/DocumentationGenerationMojo.java
@@ -26,7 +26,7 @@
 import org.apache.maven.plugins.annotations.Parameter;
 import org.apache.maven.plugins.annotations.ResolutionScope;
 import org.apache.maven.project.MavenProject;
-import org.wso2.siddhi.doc.gen.commons.NamespaceMetaData;
+import org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData;
 import org.wso2.siddhi.doc.gen.core.utils.Constants;
 import org.wso2.siddhi.doc.gen.core.utils.DocumentationUtils;
 
@@ -37,7 +37,7 @@
  * Mojo for generating Siddhi Documentation
  */
 @Mojo(
-        name = "generate",
+        name = "generate-md-docs",
         defaultPhase = LifecyclePhase.INSTALL,
         requiresDependencyResolution = ResolutionScope.TEST
 )
@@ -62,22 +62,38 @@ public class DocumentationGenerationMojo extends AbstractMojo {
     @Parameter(property = "doc.gen.directory")
     private File docGenDirectory;
 
+    /**
+     * The final output file name of the documentation
+     */
+    @Parameter(property = "doc.gen.file.name")
+    private String docGenFileName;
+
     @Override
     public void execute() throws MojoExecutionException, MojoFailureException {
+        // Setting the relevant modules target directory if not set by user
         String moduleTargetPath;
         if (moduleTargetDirectory != null) {
             moduleTargetPath = moduleTargetDirectory.getAbsolutePath();
         } else {
             moduleTargetPath = mavenProject.getBuild().getDirectory();
         }
 
+        // Setting the documentation output directory if not set by user
         String docGenPath;
         if (docGenDirectory != null) {
             docGenPath = docGenDirectory.getAbsolutePath();
         } else {
             docGenPath = mavenProject.getParent().getBasedir() + File.separator + Constants.DOCS_DIRECTORY;
         }
 
+        // Setting the documentation output file name if not set by user
+        String outputFileName;
+        if (docGenFileName != null) {
+            outputFileName = docGenFileName;
+        } else {
+            outputFileName = Constants.MARKDOWN_DOCUMENTATION_TEMPLATE;
+        }
+
         List<NamespaceMetaData> namespaceMetaDataList;
         try {
             namespaceMetaDataList = DocumentationUtils.getExtensionMetaData(
@@ -90,7 +106,10 @@ public void execute() throws MojoExecutionException, MojoFailureException {
         }
 
         if (namespaceMetaDataList.size() > 0) {
-            DocumentationUtils.generateDocumentation(namespaceMetaDataList, docGenPath);
+            DocumentationUtils.generateDocumentation(
+                    namespaceMetaDataList, docGenPath,
+                    outputFileName + Constants.MARKDOWN_FILE_EXTENSION
+            );
         }
     }
 }
diff --git a/modules/siddhi-doc-gen/src/main/java/org/wso2/siddhi/doc/gen/core/utils/Constants.java b/modules/siddhi-doc-gen/src/main/java/org/wso2/siddhi/doc/gen/core/utils/Constants.java
@@ -24,7 +24,11 @@ public class Constants {
     public static final String DOCS_DIRECTORY = "docs";
     public static final String CLASSES_DIRECTORY = "classes";
     public static final String TEMPLATES_DIRECTORY = "templates";
+
     public static final String FREEMARKER_TEMPLATE_FILE_EXTENSION = ".ftl";
     public static final String CLASS_FILE_EXTENSION = ".class";
+    public static final String MARKDOWN_FILE_EXTENSION = ".md";
+
+    public static final String MARKDOWN_DOCUMENTATION_TEMPLATE = "documentation";
     public static final String CORE_NAMESPACE = "core";
 }