com.exadatum.xsuite.xmaven.bash.doc.BashDocMojo Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of bash-maven-plugin Show documentation
Show all versions of bash-maven-plugin Show documentation
Bash Maven Plugin is used to generate documentation as well as to run unit test for bash scripts.
The newest version!
package com.exadatum.xsuite.xmaven.bash.doc;
import java.io.File;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
/*-
* #%L
* Bash Plugin
* %%
* Copyright (C) 2016 - 2018 Exadatum Software Services Pvt. Ltd.
* %%
* Licensed 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.
* #L%
*/
import org.apache.maven.doxia.sink.Sink;
import org.apache.maven.execution.MavenSession;
import org.apache.maven.plugins.annotations.Component;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import org.apache.maven.project.MavenProject;
import org.apache.maven.reporting.AbstractMavenReport;
import org.apache.maven.reporting.MavenReportException;
import org.apache.maven.shared.model.fileset.FileSet;
import org.apache.maven.shared.model.fileset.util.FileSetManager;
/**
* Generates documentation for bash functions and constants.
*/
@Mojo(name = "doc")
public class BashDocMojo extends AbstractMavenReport {
/**
* Current maven project.
*/
@Component
private MavenProject mavenProject;
/**
* Current maven session.
*/
@Component
private MavenSession mavenSession;
/**
* Document generator to be used. Plugin provides apache velocity based built
* in generator that generates document. Value of this property shall be fully
* qualified class name that implements {@link DocGenerator} interface
*/
@Parameter(property = "docGeneratorClassName")
private String docGeneratorClassName = DefaultDocPageGenerator.class
.getName();
/**
* Template to be used to generate documentation page.By default plugin looks
* for README.md.template file in the project root dir to generate the doc.
* README.md.template shall if a velocity template to which tvar_docs variable
* shall be passed. tvar_docs is a list of {@link DocBlock} objects. See
* example template at src/test/resources/README.md.template
*/
@Parameter
private File docPageTemplate;
/**
* Site directory where the documents shall be generated.
*/
@Parameter(defaultValue = "${project.build.directory}/site")
private File siteDirectory;
/**
*
* @return file set for which reports are to be generated.
*/
public List getFileSets() {
return fileSets;
}
/**
*
* @param fileSets
* file set for which reports are to be generated.
*/
public void setFileSets(final List fileSets) {
this.fileSets = fileSets;
}
/**
* List of files to be processed to generate documentation.
*/
@Parameter
private List fileSets = new ArrayList<>();
/**
* The name of the destination directory inside the site.
*/
@Parameter(property = "destDir", defaultValue = "report")
private String destDir;
/**
* Name of destination directory to store the report.
*
* @return destDir appended with report
*/
@Override
public String getOutputName() {
return destDir + "/report";
}
/**
* Name of the plugin.
*
* @param locale
* @return name
*/
@Override
public String getName(final Locale locale) {
return "Bash Maven Report";
}
/**
* Short description of the plugin.
*
* @param locale
* @return description.
*/
@Override
public String getDescription(final Locale locale) {
return "Documentation for Bash Functions and Constants";
}
/**
*
* @param docGeneratorClassName
* the type of doc generator to be used.
*/
public void setDocGeneratorClassName(final String docGeneratorClassName) {
this.docGeneratorClassName = docGeneratorClassName;
}
/*
* (non-Javadoc)
*
* @see org.apache.maven.plugin.Mojo#executeReport()
*/
@Override
protected void executeReport(final Locale locale)
throws MavenReportException {
FileSetManager fileSetManager = new FileSetManager();
List docBlocks = new ArrayList<>();
addDefaultFileSetIfNotConfigured();
for (FileSet fileSet : fileSets) {
String[] includedFiles = fileSetManager.getIncludedFiles(fileSet);
for (int i = 0; i < includedFiles.length; i++) {
File includedFile = new File(fileSet.getDirectory(),
includedFiles[i]);
try {
docBlocks = generateDoc(includedFile);
Sink sink = getSink();
DocGenerator docGenerator = getDocGenerator();
DocGeneratorContext context = new DocGeneratorContext();
context.setDocBlocks(docBlocks);
context.setOutputPage(siteDirectory);
context.setPageTemplate(docPageTemplate);
context.setFileName(includedFile.getName().replace(".sh", ""));
context.setSink(sink);
docGenerator.generate(context);
} catch (Exception e) {
getLog().error(
"Failed to parse bash script " + includedFile.getAbsolutePath(),
e);
}
}
}
if (docBlocks.isEmpty()) {
getLog().warn("No documentation blocks found");
}
}
/**
* If user do not configure this plugin with fileset information then we
* switch to default directories.
*/
private void addDefaultFileSetIfNotConfigured() {
if (fileSets.isEmpty()) {
FileSet fileSet = new FileSet();
fileSet.setDirectory("src/main/bin");
// fileSet.setDirectory("src/main/resources/bin");
// fileSet.addInclude("src/main/resources/bin");
fileSets.add(fileSet);
}
}
/**
* Get the type of Doc Generator.
*
* @return docGenerator
*/
private DocGenerator getDocGenerator() {
DocGenerator docGenerator;
try {
Object newInstance = Class.forName(docGeneratorClassName).newInstance();
if (newInstance instanceof DocGenerator) {
docGenerator = (DocGenerator) newInstance;
} else {
throw new RuntimeException(String.format(
"Invalid doc generator implementation [%s]."
+ "Doc generator shall implement [%s] interface ",
docGeneratorClassName, DocGenerator.class.getName()));
}
} catch (InstantiationException | IllegalAccessException
| ClassNotFoundException e) {
throw new RuntimeException(e);
}
return docGenerator;
}
/**
* Generate Documentation from bash script.
*
* @param bashScript
* Script for which documentation is to be generated.
* @return list of DocBlock.
* @throws IOException
* IOException.
*/
public List generateDoc(final File bashScript)
throws IOException {
List docs = new ArrayList<>();
String contents = getBashScriptContents(bashScript);
DocBlockIterator blockIterator = new DocBlockIterator(contents);
while (blockIterator.hasNext()) {
DocBlock docBlock = blockIterator.next();
docs.add(docBlock);
}
return docs;
}
/**
* It is assumed that bash scripts are small files.
*
* @param bashScript
* bash script file
* @return contents of bash script
* @throws IOException
* IOException
*/
private String getBashScriptContents(final File bashScript)
throws IOException {
return new String(Files.readAllBytes(bashScript.toPath()),
StandardCharsets.UTF_8);
}
}