nadundesilva/GSoC_2017.md

## GSoC_2017.md

      
    Raw
  

              GSoC_2017.md
            
          
    Siddhi Extension Doc Auto Generation

About the Siddhi Engine

Siddhi is a lightweight, easy-to-use Open Source Complex Event Processing Engine (CEP) released as a Java Library under Apache Software License v2.0. Siddhi CEP process events generated by various event sources, analyze them and notifies appropriate complex events according to the user specified queries.
About the Project

This project consists of two main parts of the automated generation of documentation for Siddhi Complex Event Processing Engine.

a maven plugin for automated documentation generation for a single extension module or the siddhi core. The metadata annotated using the @Extension annotation are retrieved using the ClassIndex library which is already used by siddhi for indexing the annotated processor classes. Afterwards, documentation is generated using the metadata using a template engine.
Creating an index of the Siddhi Extension Repositories.
Adding and committing the docs/ directory content and the mkdocs.yml file to Git. Pushing the changes in the docs/ directory content and the mkdocs.yml file to origin master. Automatically deploying documentation in each new release of Siddhi.

A deployed documentation generated by the plugin can be found here
Mentors


Sriskandarajah Suhothayan
Nirmal Fernando

Mail Thread

You can find the publicly available mail thread, corresponding to this project, maintained by WSO2 Oxygen Tank, here
Commits


79236ac4f9ca11ac525f6a18e10c897062ab2f6a
c9caa14906a23b38e10e5f10097ab54dd1c1dc90
4503ea50734a1c9553644d8a00bd11ff6036369d
82ed42a83fcdceaeb3ac9114676b1f0c4c54abba
0486d636e6365976485a84a7ef3b928ab246ab85
78b2562bf147d624267ee023d13278b81fde8ca6
0f338073e13744030de30bac276ed462da52b0f7
f7ab1ec86b923d04d45a0b5811f75dca2c671d31
d890d0b853a476b5a1d14dc61b3cf4096f02d450
04a907d2f5055dbc56efad499fe7e5da466de61a
a46bcc9f4c9db680f39d37d814cfa26d976b97de
cf3297c315f43f8cbaec5d368ab59da08bbce572
97503702a6fb5e7281b037f5e24aa43492923d3e

Pull Requests


PR #417
PR #442
PR #444
PR #445
PR #478
PR #484
PR #493

Siddhi Documentation Generation Module

Siddhi Documentation Generation Plugin was the main product of this project and was added as a module to the main siddhi repository. This contains a maven plugin which is used by the Siddhi Repository for Generating Documentation.
How to Use

Documentation Generation (generate-md-docs)

Add the following to the pom file of the module containing the extension classes. (Please note that all configuration parameters are not required. Check the configuration section).
The filename of the generated documentation file is inferred based on the project version and this file will be generated inside the api/ directory inside the docGenBaseDirectory. The home page would be updated accordingly as well with a list of versions available in the api/ directory.
<plugin>
   <groupId>org.wso2.siddhi</groupId>
   <artifactId>siddhi-doc-gen</artifactId>
   <version>${siddhi.version}</version>
   <executions>
       <execution>
           <goals>
               <goal>generate-md-docs</goal>
           </goals>
       </execution>
   </executions>
   <configuration>
       <moduleTargetDirectory>../target/</moduleTargetDirectory>
       <homePageTemplateFile>../../../README.md</homePageTemplateFile>
       <mkdocsConfigFile>../../../mkdocs.yml</mkdocsConfigFile>
       <docGenBaseDirectory>../../../docs/</docGenBaseDirectory>
       <homePageFileName>index</homePageFileName>
       <readMeFile>../../../README.md</readMeFile>
   </configuration>
</plugin>

Configuration


      Configuration
      Optional
      Default Value
      Description
   
   
      moduleTargetDirectory
      Yes
      {current-module-build-directory}/
      The build directory (“target/” directory) from which the extension metadata will be retrieved. The class files in the classes directory in the build directory will be loaded and from them the annotated metadata will be retrieved.
   
   
      homePageTemplateFile
      Yes
      {root-maven-module-directory}/README.md
      The path to the hoem page template file. The content of this file will be copied to the top of the mkdocs homepage with a list of “API Docs” at the bottom.
   
   
      mkdocsConfigFile
      Yes
      {root-maven-module-directory}/mkdocs.yml
      The path to the mkdocs configuration file
   
   
      docGenBaseDirectory
      Yes
      {root-maven-module-directory}/docs/
      The base directory in which the documentation files will be generated.
   
   
      homePageFileName
      Yes
      index
      The name of the home page file that will be used by mkdocs. This is relative to the docGenBaseDirectory.Markdown file extension (.md) is automatically added.
   
   
      readmeFile
      Yes
      {root-maven-module-directory}/README.md
      The README file of the project
   

Extensions Index Generation (generate-extensions-index)

Add the following to the pom file of the siddhi main repository’s siddhi-core-doc-gen module. (Please note that all configuration parameters are not required. Check the configuration section)
<plugin>
   <groupId>org.wso2.siddhi</groupId>
   <artifactId>siddhi-doc-gen</artifactId>
   <version>${siddhi.version}</version>
   <executions>
       <execution>
           <goals>
               <goal>generate-extensions-index</goal>
           </goals>
       </execution>
   </executions>
   <configuration>
       <docGenBaseDirectory>../../../docs/</docGenBaseDirectory>
       <indexGenFileName>extensions</indexGenFileName>

       <extensionRepositoryOwner>wso2-extensions</extensionRepositoryOwner>
       <extensionRepositories>
           <extensionRepository>siddhi-map-xml</extensionRepository>
           <extensionRepository>siddhi-execution-extrema</extensionRepository>
           <extensionRepository>siddhi-execution-math</extensionRepository>
           <extensionRepository>siddhi-gpl-execution-geo</extensionRepository>
       </extensionRepositories>
   </configuration>
</plugin>

Configuration


      Configuration
      Optional
      Default Value
      Description
   
   
      extensionRepositories
      No
      None
      The extension repositories names list.
   
   
      extensionRepositoryOwner
      Yes
      wso2-extensions
      The owner (On GitHub) of the extension repository.
   
   
      docGenBaseDirectory
      Yes
      {root-maven-module-directory}/docs/
      The directory in which the index file will be generated.
   
   
      indexGenFileName
      Yes
      extensions
      The name of the output extensions index file that will be generated. This is relative to the docGenBaseDirectory. Markdown file extension (.md) is automatically added.
   

MkDocs site Deployment on GitHub Pages (deploy-mkdocs-github-pages)

Add the following to the pom file. (Please note that all configuration parameters are not required. Check the configuration section)
<plugin>
   <groupId>org.wso2.siddhi</groupId>
   <artifactId>siddhi-doc-gen</artifactId>
   <version>${siddhi.version}</version>
   <executions>
       <execution>
           <goals>
               <goal>deploy-mkdocs-github-pages</goal>
           </goals>
       </execution>
   </executions>
   <configuration>
       <mkdocsConfigFile>../../../mkdocs.yml</mkdocsConfigFile>
       <docGenBaseDirectory>../../../docs/</docGenBaseDirectory>
       <readMeFile>../../../README.md</readMeFile>
   </configuration>
</plugin>

Automating the goal execution with maven release plugin

This goal is intended to be run as a preparation step of the prepare goal of the maven release plugin. This can be achieved using maven profiles. To do so use the following steps.

Add a profile and add the plugin goal to the profile
<profile>
   <id>documentation-deploy</id>
   <build>
      <plugins>
         <plugin>
            <groupId>org.wso2.siddhi</groupId>
            <artifactId>siddhi-doc-gen</artifactId>
            <executions>
               <execution>
                  <phase>compile</phase>
                  <goals>
                     <goal>deploy-mkdocs-github-pages</goal>
                  </goals>
               </execution>
            </executions>
         </plugin>
      </plugins>
   </build>
</profile>


Activate the profile in the preparation goal of the release:prepare goal
<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-release-plugin</artifactId>
   <configuration>
      <preparationGoals>clean install -Pdocumentation-deploy</preparationGoals>
      <autoVersionSubmodules>true</autoVersionSubmodules>
   </configuration>
</plugin>


Configuration


      Configuration
      Optional
      Default Value
      Description
   
   
      mkdocsConfigFile
      Yes
      {root-maven-module-directory}/mkdocs.yml
      The path to the mkdocs configuration file
   
   
      docGenBaseDirectory
      Yes
      {root-maven-module-directory}/docs/
      The directory in which the index file will be generated.
   
   
      readmeFile
      Yes
      {root-maven-module-directory}/README.md
      The README file of the project
   

Special Notations in homePageTemplate

By adding the following headings in the home page template file, sections containing useful information can be generated automatically in the home page. If the heading names need to be changed, a source code level change is required in the Constants class in the siddhi-doc-gen module.

## Features
## Latest API Docs

## Features

The heading "## Features" can be used for adding a section in the homePageTemplate(README.md file by default). Adding this heading will replace the content below it until a heading of equal level or higher is encountered with a list of extension processors adn their descriptions.
## Latest API Docs

The heading "## Latest API Docs" can be used for adding a section in the homePageTemplate(README.md file by default). Adding this heading will replace the content below it until a heading of equal level or higher is encountered with a link to the latest API Docs version.
How to add a new Extension (Source code level changes)


Add the new extension to ExtensionType enum class and add the superclass of the extension type to the superClassMap hash map. (The value of the enums should be similar to the actual names used throughout all the documentation. This will affect the names displayed in the documentation as well as the hyperlinks)
Update the documentation.md.ftl to support the new extension type
Configuration	Optional	Default Value	Description
`moduleTargetDirectory`	Yes	`{current-module-build-directory}/`	The build directory (“target/” directory) from which the extension metadata will be retrieved. The class files in the classes directory in the build directory will be loaded and from them the annotated metadata will be retrieved.
`homePageTemplateFile`	Yes	`{root-maven-module-directory}/README.md`	The path to the hoem page template file. The content of this file will be copied to the top of the mkdocs homepage with a list of “API Docs” at the bottom.
`mkdocsConfigFile`	Yes	`{root-maven-module-directory}/mkdocs.yml`	The path to the mkdocs configuration file
`docGenBaseDirectory`	Yes	`{root-maven-module-directory}/docs/`	The base directory in which the documentation files will be generated.
`homePageFileName`	Yes	`index`	The name of the home page file that will be used by mkdocs. This is relative to the docGenBaseDirectory.Markdown file extension (.md) is automatically added.
`readmeFile`	Yes	`{root-maven-module-directory}/README.md`	The README file of the project
Configuration	Optional	Default Value	Description
`extensionRepositories`	No	None	The extension repositories names list.
`extensionRepositoryOwner`	Yes	`wso2-extensions`	The owner (On GitHub) of the extension repository.
`docGenBaseDirectory`	Yes	`{root-maven-module-directory}/docs/`	The directory in which the index file will be generated.
`indexGenFileName`	Yes	`extensions`	The name of the output extensions index file that will be generated. This is relative to the docGenBaseDirectory. Markdown file extension (.md) is automatically added.