Search in sources :

Example 1 with NamespaceMetaData

use of org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData in project siddhi by wso2.

the class DocumentationUtils method addExtensionMetaDataIntoNamespaceList.

/**
 * Generate extension meta data from the annotated data in the class
 *
 * @param namespaceList  The list of namespaces to which the new extension will be added
 * @param extensionClass Class from which meta data should be extracted from
 * @param logger         The maven plugin logger
 */
private static void addExtensionMetaDataIntoNamespaceList(List<NamespaceMetaData> namespaceList, Class<?> extensionClass, Log logger) {
    Extension extensionAnnotation = extensionClass.getAnnotation(Extension.class);
    if (extensionAnnotation != null) {
        // Discarding extension classes without annotation
        ExtensionMetaData extensionMetaData = new ExtensionMetaData();
        // Finding extension type
        String extensionType = null;
        for (Map.Entry<ExtensionType, Class<?>> entry : ExtensionType.getSuperClassMap().entrySet()) {
            Class<?> superClass = entry.getValue();
            if (superClass.isAssignableFrom(extensionClass) && superClass != extensionClass) {
                extensionType = entry.getKey().getValue();
                break;
            }
        }
        // Discarding the extension if it belongs to an unknown type
        if (extensionType == null) {
            logger.warn("Discarding extension (belonging to an unknown extension type): " + extensionClass.getCanonicalName());
            return;
        }
        extensionMetaData.setName(extensionAnnotation.name());
        extensionMetaData.setDescription(extensionAnnotation.description());
        // Adding query parameters
        ParameterMetaData[] parameters = new ParameterMetaData[extensionAnnotation.parameters().length];
        for (int i = 0; i < extensionAnnotation.parameters().length; i++) {
            Parameter parameterAnnotation = extensionAnnotation.parameters()[i];
            ParameterMetaData parameter = new ParameterMetaData();
            parameter.setName(parameterAnnotation.name());
            parameter.setType(Arrays.asList(parameterAnnotation.type()));
            parameter.setDescription(parameterAnnotation.description());
            parameter.setOptional(parameterAnnotation.optional());
            parameter.setDynamic(parameterAnnotation.dynamic());
            parameter.setDefaultValue(parameterAnnotation.defaultValue());
            parameters[i] = parameter;
        }
        extensionMetaData.setParameters(Arrays.asList(parameters));
        // Adding system parameters
        SystemParameterMetaData[] systemParameters = new SystemParameterMetaData[extensionAnnotation.systemParameter().length];
        for (int i = 0; i < extensionAnnotation.systemParameter().length; i++) {
            SystemParameter systemParameterAnnotation = extensionAnnotation.systemParameter()[i];
            SystemParameterMetaData systemParameter = new SystemParameterMetaData();
            systemParameter.setName(systemParameterAnnotation.name());
            systemParameter.setDescription(systemParameterAnnotation.description());
            systemParameter.setDefaultValue(systemParameterAnnotation.defaultValue());
            systemParameter.setPossibleParameters(Arrays.asList(systemParameterAnnotation.possibleParameters()));
            systemParameters[i] = systemParameter;
        }
        extensionMetaData.setSystemParameters(Arrays.asList(systemParameters));
        // Adding return attributes
        ReturnAttributeMetaData[] returnAttributes = new ReturnAttributeMetaData[extensionAnnotation.returnAttributes().length];
        for (int i = 0; i < extensionAnnotation.returnAttributes().length; i++) {
            ReturnAttribute parameterAnnotation = extensionAnnotation.returnAttributes()[i];
            ReturnAttributeMetaData returnAttribute = new ReturnAttributeMetaData();
            returnAttribute.setName(parameterAnnotation.name());
            returnAttribute.setType(Arrays.asList(parameterAnnotation.type()));
            returnAttribute.setDescription(parameterAnnotation.description());
            returnAttributes[i] = returnAttribute;
        }
        extensionMetaData.setReturnAttributes(Arrays.asList(returnAttributes));
        // Adding examples
        ExampleMetaData[] examples = new ExampleMetaData[extensionAnnotation.examples().length];
        for (int i = 0; i < extensionAnnotation.examples().length; i++) {
            Example exampleAnnotation = extensionAnnotation.examples()[i];
            ExampleMetaData exampleMetaData = new ExampleMetaData();
            exampleMetaData.setSyntax(exampleAnnotation.syntax());
            exampleMetaData.setDescription(exampleAnnotation.description());
            examples[i] = exampleMetaData;
        }
        extensionMetaData.setExamples(Arrays.asList(examples));
        // Finding the namespace
        String namespaceName = extensionAnnotation.namespace();
        if (Objects.equals(namespaceName, "")) {
            namespaceName = Constants.CORE_NAMESPACE;
        }
        // Finding the relevant namespace in the namespace list
        NamespaceMetaData namespace = null;
        for (NamespaceMetaData existingNamespace : namespaceList) {
            if (Objects.equals(existingNamespace.getName(), namespaceName)) {
                namespace = existingNamespace;
                break;
            }
        }
        // Creating namespace if it doesn't exist
        if (namespace == null) {
            namespace = new NamespaceMetaData();
            namespace.setName(namespaceName);
            namespace.setExtensionMap(new TreeMap<>());
            namespaceList.add(namespace);
        }
        // Adding to the relevant extension metadata list in the namespace
        List<ExtensionMetaData> extensionMetaDataList = namespace.getExtensionMap().computeIfAbsent(extensionType, k -> new ArrayList<>());
        extensionMetaDataList.add(extensionMetaData);
    }
}
Also used : ReturnAttribute(org.wso2.siddhi.annotation.ReturnAttribute) Example(org.wso2.siddhi.annotation.Example) SystemParameter(org.wso2.siddhi.annotation.SystemParameter) ExampleMetaData(org.wso2.siddhi.doc.gen.commons.metadata.ExampleMetaData) NamespaceMetaData(org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData) Extension(org.wso2.siddhi.annotation.Extension) ReturnAttributeMetaData(org.wso2.siddhi.doc.gen.commons.metadata.ReturnAttributeMetaData) ExtensionType(org.wso2.siddhi.doc.gen.commons.metadata.ExtensionType) ExtensionMetaData(org.wso2.siddhi.doc.gen.commons.metadata.ExtensionMetaData) SystemParameterMetaData(org.wso2.siddhi.doc.gen.commons.metadata.SystemParameterMetaData) SystemParameter(org.wso2.siddhi.annotation.SystemParameter) Parameter(org.wso2.siddhi.annotation.Parameter) Map(java.util.Map) HashMap(java.util.HashMap) TreeMap(java.util.TreeMap) ParameterMetaData(org.wso2.siddhi.doc.gen.commons.metadata.ParameterMetaData) SystemParameterMetaData(org.wso2.siddhi.doc.gen.commons.metadata.SystemParameterMetaData)

Example 2 with NamespaceMetaData

use of org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData in project siddhi by wso2.

the class MkdocsGitHubPagesDeployMojo method execute.

@Override
public void execute() throws MojoExecutionException, MojoFailureException {
    // Finding the root maven project
    MavenProject rootMavenProject = mavenProject;
    while (rootMavenProject.getParent().getBasedir() != null) {
        rootMavenProject = rootMavenProject.getParent();
    }
    // 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 mkdocs config file path if not set by user
    if (mkdocsConfigFile == null) {
        mkdocsConfigFile = new File(rootMavenProject.getBasedir() + File.separator + Constants.MKDOCS_CONFIG_FILE_NAME + Constants.YAML_FILE_EXTENSION);
    }
    // Setting the documentation output directory if not set by user
    String docGenBasePath;
    if (docGenBaseDirectory != null) {
        docGenBasePath = docGenBaseDirectory.getAbsolutePath();
    } else {
        docGenBasePath = rootMavenProject.getBasedir() + File.separator + Constants.DOCS_DIRECTORY;
    }
    // Setting the home page file name if not set by user
    File homePageFile;
    if (homePageFileName == null) {
        homePageFile = new File(docGenBasePath + File.separator + Constants.HOMEPAGE_FILE_NAME + Constants.MARKDOWN_FILE_EXTENSION);
    } else {
        homePageFile = new File(docGenBasePath + File.separator + homePageFileName);
    }
    // Setting the readme file name if not set by user
    if (readmeFile == null) {
        readmeFile = new File(rootMavenProject.getBasedir() + File.separator + Constants.README_FILE_NAME + Constants.MARKDOWN_FILE_EXTENSION);
    }
    // Setting the home page template file path if not set by user
    if (homePageTemplateFile == null) {
        homePageTemplateFile = new File(rootMavenProject.getBasedir() + File.separator + Constants.README_FILE_NAME + Constants.MARKDOWN_FILE_EXTENSION);
    }
    // Retrieving metadata
    List<NamespaceMetaData> namespaceMetaDataList;
    try {
        namespaceMetaDataList = DocumentationUtils.getExtensionMetaData(moduleTargetPath, mavenProject.getRuntimeClasspathElements(), getLog());
    } catch (DependencyResolutionRequiredException e) {
        throw new MojoFailureException("Unable to resolve dependencies of the project", e);
    }
    // Generating the documentation
    if (namespaceMetaDataList.size() > 0) {
        DocumentationUtils.generateDocumentation(namespaceMetaDataList, docGenBasePath, mavenProject.getVersion(), getLog());
        DocumentationUtils.updateHeadingsInMarkdownFile(homePageTemplateFile, homePageFile, rootMavenProject.getArtifactId(), mavenProject.getVersion(), namespaceMetaDataList);
        DocumentationUtils.updateHeadingsInMarkdownFile(readmeFile, readmeFile, rootMavenProject.getArtifactId(), mavenProject.getVersion(), namespaceMetaDataList);
    }
    // Delete snapshot files
    DocumentationUtils.removeSnapshotAPIDocs(mkdocsConfigFile, docGenBasePath, getLog());
    // Updating the links in the home page to the mkdocs config
    try {
        updateAPIPagesInMkdocsConfig(mkdocsConfigFile, docGenBasePath);
    } catch (FileNotFoundException e) {
        getLog().warn("Unable to find mkdocs configuration file: " + mkdocsConfigFile.getAbsolutePath() + ". Mkdocs configuration file not updated.");
    }
    // Deploying the documentation
    if (DocumentationUtils.generateMkdocsSite(mkdocsConfigFile, getLog())) {
        // Creating the credential provider fot Git
        String scmUsername = System.getenv(Constants.SYSTEM_PROPERTY_SCM_USERNAME_KEY);
        String scmPassword = System.getenv(Constants.SYSTEM_PROPERTY_SCM_PASSWORD_KEY);
        if (scmUsername == null && scmPassword == null) {
            getLog().info("SCM_USERNAME and SCM_PASSWORD not defined!");
        }
        String url = null;
        Scm scm = rootMavenProject.getScm();
        if (scm != null) {
            url = scm.getUrl();
        }
        // Deploying documentation
        DocumentationUtils.updateDocumentationOnGitHub(docGenBasePath, mkdocsConfigFile, readmeFile, mavenProject.getVersion(), getLog());
        DocumentationUtils.deployMkdocsOnGitHubPages(mavenProject.getVersion(), rootMavenProject.getBasedir(), url, scmUsername, scmPassword, getLog());
    } else {
        getLog().warn("Unable to generate documentation. Skipping documentation deployment.");
    }
}
Also used : DependencyResolutionRequiredException(org.apache.maven.artifact.DependencyResolutionRequiredException) MavenProject(org.apache.maven.project.MavenProject) NamespaceMetaData(org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData) MojoFailureException(org.apache.maven.plugin.MojoFailureException) FileNotFoundException(java.io.FileNotFoundException) Scm(org.apache.maven.model.Scm) File(java.io.File)

Example 3 with NamespaceMetaData

use of org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData in project siddhi by wso2.

the class DocumentationUtils method generateDocumentation.

/**
 * Generate documentation related files using metadata
 *
 * @param namespaceMetaDataList      Metadata in this repository
 * @param documentationBaseDirectory The path of the directory in which the documentation will be generated
 * @param documentationVersion       The version of the documentation being generated
 * @param logger                     The logger to log errors
 * @throws MojoFailureException if the Mojo fails to find template file or create new documentation file
 */
public static void generateDocumentation(List<NamespaceMetaData> namespaceMetaDataList, String documentationBaseDirectory, String documentationVersion, Log logger) throws MojoFailureException {
    // Generating data model
    Map<String, Object> rootDataModel = new HashMap<>();
    rootDataModel.put("metaData", namespaceMetaDataList);
    rootDataModel.put("formatDescription", new FormatDescriptionMethod());
    rootDataModel.put("latestDocumentationVersion", documentationVersion);
    String outputFileRelativePath = Constants.API_SUB_DIRECTORY + File.separator + documentationVersion + Constants.MARKDOWN_FILE_EXTENSION;
    generateFileFromTemplate(Constants.MARKDOWN_DOCUMENTATION_TEMPLATE + Constants.MARKDOWN_FILE_EXTENSION + Constants.FREEMARKER_TEMPLATE_FILE_EXTENSION, rootDataModel, documentationBaseDirectory, outputFileRelativePath);
    File newVersionFile = new File(documentationBaseDirectory + File.separator + outputFileRelativePath);
    File latestLabelFile = new File(documentationBaseDirectory + File.separator + Constants.API_SUB_DIRECTORY + File.separator + Constants.LATEST_FILE_NAME + Constants.MARKDOWN_FILE_EXTENSION);
    try {
        Files.copy(newVersionFile, latestLabelFile);
    } catch (IOException e) {
        logger.warn("Failed to generate latest.md file", e);
    }
}
Also used : HashMap(java.util.HashMap) FormatDescriptionMethod(org.wso2.siddhi.doc.gen.core.freemarker.FormatDescriptionMethod) IOException(java.io.IOException) File(java.io.File)

Example 4 with NamespaceMetaData

use of org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData in project siddhi by wso2.

the class DocumentationUtils method getExtensionMetaData.

/**
 * Returns the extension extension meta data
 * Gets the meta data from the siddhi manager
 *
 * @param targetDirectoryPath The path of the target directory of the maven module containing extensions
 * @param logger              The maven plugin logger
 * @return NamespaceMetaData namespace meta data list
 * @throws MojoFailureException   If this fails to access project dependencies
 * @throws MojoExecutionException If the classes directory from which classes are loaded is invalid
 */
public static List<NamespaceMetaData> getExtensionMetaData(String targetDirectoryPath, List<String> runtimeClasspathElements, Log logger) throws MojoFailureException, MojoExecutionException {
    List<NamespaceMetaData> namespaceMetaDataList = new ArrayList<NamespaceMetaData>();
    // +1 to include the module's target/classes folder
    int urlCount = runtimeClasspathElements.size() + 1;
    // Creating a list of URLs with all project dependencies
    URL[] urls = new URL[urlCount];
    for (int i = 0; i < runtimeClasspathElements.size(); i++) {
        try {
            urls[i] = new File(runtimeClasspathElements.get(i)).toURI().toURL();
        } catch (MalformedURLException e) {
            throw new MojoFailureException("Unable to access project dependency: " + runtimeClasspathElements.get(i), e);
        }
    }
    File classesDirectory = new File(targetDirectoryPath + File.separator + Constants.CLASSES_DIRECTORY);
    try {
        // Adding the generated classes to the class loader
        urls[urlCount - 1] = classesDirectory.toURI().toURL();
        ClassLoader urlClassLoader = AccessController.doPrivileged((PrivilegedAction<ClassLoader>) () -> new URLClassLoader(urls, Thread.currentThread().getContextClassLoader()));
        // Getting extensions from all the class files in the classes directory
        addExtensionInDirectory(classesDirectory, classesDirectory.getAbsolutePath(), urlClassLoader, namespaceMetaDataList, logger);
    } catch (MalformedURLException e) {
        throw new MojoExecutionException("Invalid classes directory: " + classesDirectory.getAbsolutePath(), e);
    }
    for (NamespaceMetaData aNamespaceMetaData : namespaceMetaDataList) {
        for (List<ExtensionMetaData> extensionMetaData : aNamespaceMetaData.getExtensionMap().values()) {
            Collections.sort(extensionMetaData);
        }
    }
    Collections.sort(namespaceMetaDataList);
    return namespaceMetaDataList;
}
Also used : MalformedURLException(java.net.MalformedURLException) MojoExecutionException(org.apache.maven.plugin.MojoExecutionException) NamespaceMetaData(org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData) ArrayList(java.util.ArrayList) MojoFailureException(org.apache.maven.plugin.MojoFailureException) URL(java.net.URL) URLClassLoader(java.net.URLClassLoader) ExtensionMetaData(org.wso2.siddhi.doc.gen.commons.metadata.ExtensionMetaData) URLClassLoader(java.net.URLClassLoader) File(java.io.File)

Example 5 with NamespaceMetaData

use of org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData in project siddhi by wso2.

the class MarkdownDocumentationGenerationMojo method execute.

@Override
public void execute() throws MojoExecutionException, MojoFailureException {
    // Finding the root maven project
    MavenProject rootMavenProject = mavenProject;
    while (rootMavenProject.getParent().getBasedir() != null) {
        rootMavenProject = rootMavenProject.getParent();
    }
    // 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 docGenBasePath;
    if (docGenBaseDirectory != null) {
        docGenBasePath = docGenBaseDirectory.getAbsolutePath();
    } else {
        docGenBasePath = rootMavenProject.getBasedir() + File.separator + Constants.DOCS_DIRECTORY;
    }
    // Setting the mkdocs config file path if not set by user
    if (mkdocsConfigFile == null) {
        mkdocsConfigFile = new File(rootMavenProject.getBasedir() + File.separator + Constants.MKDOCS_CONFIG_FILE_NAME + Constants.YAML_FILE_EXTENSION);
    }
    // Setting the readme file name if not set by user
    if (readmeFile == null) {
        readmeFile = new File(rootMavenProject.getBasedir() + File.separator + Constants.README_FILE_NAME + Constants.MARKDOWN_FILE_EXTENSION);
    }
    // Retrieving metadata
    List<NamespaceMetaData> namespaceMetaDataList;
    try {
        namespaceMetaDataList = DocumentationUtils.getExtensionMetaData(moduleTargetPath, mavenProject.getRuntimeClasspathElements(), getLog());
    } catch (DependencyResolutionRequiredException e) {
        throw new MojoFailureException("Unable to resolve dependencies of the project", e);
    }
    // Generating the documentation
    if (namespaceMetaDataList.size() > 0) {
        DocumentationUtils.generateDocumentation(namespaceMetaDataList, docGenBasePath, mavenProject.getVersion(), getLog());
    // DocumentationUtils.updateHeadingsInMarkdownFile(homePageTemplateFile, homePageFile,
    // rootMavenProject.getArtifactId(), mavenProject.getVersion(), namespaceMetaDataList);
    // DocumentationUtils.updateHeadingsInMarkdownFile(readmeFile, readmeFile, rootMavenProject.getArtifactId(),
    // mavenProject.getVersion(), namespaceMetaDataList);
    }
}
Also used : DependencyResolutionRequiredException(org.apache.maven.artifact.DependencyResolutionRequiredException) MavenProject(org.apache.maven.project.MavenProject) NamespaceMetaData(org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData) MojoFailureException(org.apache.maven.plugin.MojoFailureException) File(java.io.File)

Aggregations

File (java.io.File)4 NamespaceMetaData (org.wso2.siddhi.doc.gen.commons.metadata.NamespaceMetaData)4 HashMap (java.util.HashMap)3 MojoFailureException (org.apache.maven.plugin.MojoFailureException)3 IOException (java.io.IOException)2 ArrayList (java.util.ArrayList)2 DependencyResolutionRequiredException (org.apache.maven.artifact.DependencyResolutionRequiredException)2 MavenProject (org.apache.maven.project.MavenProject)2 ExtensionMetaData (org.wso2.siddhi.doc.gen.commons.metadata.ExtensionMetaData)2 FormatDescriptionMethod (org.wso2.siddhi.doc.gen.core.freemarker.FormatDescriptionMethod)2 FileNotFoundException (java.io.FileNotFoundException)1 MalformedURLException (java.net.MalformedURLException)1 URL (java.net.URL)1 URLClassLoader (java.net.URLClassLoader)1 Map (java.util.Map)1 TreeMap (java.util.TreeMap)1 Scm (org.apache.maven.model.Scm)1 MojoExecutionException (org.apache.maven.plugin.MojoExecutionException)1 Example (org.wso2.siddhi.annotation.Example)1 Extension (org.wso2.siddhi.annotation.Extension)1