ApidocMojo.java

/*
 * #%L
 * API Documentation Plugin
 * %%
 * Copyright (C) 2012 Perka Inc.
 * %%
 * 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%
 */
package com.getperka.flatpack.apidoc;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.Reader;
import java.io.Writer;
import java.nio.charset.Charset;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.TreeMap;

import org.apache.maven.artifact.Artifact;
import org.apache.maven.artifact.factory.ArtifactFactory;
import org.apache.maven.artifact.metadata.ArtifactMetadataSource;
import org.apache.maven.artifact.repository.ArtifactRepository;
import org.apache.maven.artifact.resolver.ArtifactNotFoundException;
import org.apache.maven.artifact.resolver.ArtifactResolutionException;
import org.apache.maven.artifact.resolver.ArtifactResolutionResult;
import org.apache.maven.artifact.resolver.ArtifactResolver;
import org.apache.maven.model.Resource;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.project.MavenProject;
import org.codehaus.plexus.util.IOUtil;
import org.codehaus.plexus.util.Scanner;
import org.sonatype.plexus.build.incremental.BuildContext;
import org.tautua.markdownpapers.HtmlEmitter;
import org.tautua.markdownpapers.ast.Code;
import org.tautua.markdownpapers.ast.CodeText;
import org.tautua.markdownpapers.ast.Document;
import org.tautua.markdownpapers.ast.Header;
import org.tautua.markdownpapers.ast.ParserTreeConstants;
import org.tautua.markdownpapers.ast.Tag;
import org.tautua.markdownpapers.ast.TagAttribute;
import org.tautua.markdownpapers.ast.Text;
import org.tautua.markdownpapers.parser.ParseException;
import org.tautua.markdownpapers.parser.Parser;

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import com.google.gson.stream.JsonWriter;

/**
 * Generate API documentation using a Doclet and include it in the project's output.
 *
 * @goal apidoc
 * @phase process-sources
 * @threadSafe
 */
public class ApidocMojo extends AbstractMojo {
  /**
   * A subclass of HtmlEmitter that spies on the document to retrieve the first header to use as a
   * title string.
   */
  private class TitleSpyHtmlEmitter extends HtmlEmitter {
    private boolean seenHeader;
    private boolean spyOnText;
    private final StringBuilder text = new StringBuilder();

    private TitleSpyHtmlEmitter(Appendable buffer) {
      super(buffer);
    }

    public String getTitle() {
      return text.toString().trim();
    }

    @Override
    public void visit(Header node) {
      boolean doIt = !seenHeader;
      if (node.getLevel() == 1 && doIt) {
        seenHeader = true;
        spyOnText = true;
      }
      super.visit(node);
      if (doIt) {
        spyOnText = false;
      }
    }

    @Override
    public void visit(Tag node) {
      if (!"example".equals(node.getName())) {
        super.visit(node);
        return;
      }
      String className = null;
      String methodDesc = null;
      for (TagAttribute attr : node.getAttributes()) {
        if ("class".equals(attr.getName())) {
          className = attr.getValue();
        } else if ("method".equals(attr.getName())) {
          methodDesc = attr.getValue();
        }
      }

      String contents;

      if (className == null || methodDesc == null) {
        contents = "example tag must specify class and method attributes";
      } else {
        String key = className + ":" + methodDesc + ":contents";
        File f = findPackageJson(className);
        if (f == null) {
          contents = "Cannot find package.json for " + className;
        } else {
          InputStreamReader reader;
          try {
            reader = new InputStreamReader(new FileInputStream(f), UTF8);
          } catch (FileNotFoundException e) {
            // The canRead() above should prevent this
            throw new RuntimeException(e);
          }
          JsonObject obj = new JsonParser().parse(reader).getAsJsonObject();
          if (obj.has(key)) {
            contents = obj.get(key).getAsString();
          } else {
            contents = "No @Example annotation? " + key;
          }
        }
      }

      CodeText codeText = new CodeText(ParserTreeConstants.JJTCODETEXT);
      codeText.append(contents);
      Code code = new Code(ParserTreeConstants.JJTCODE);
      code.jjtAddChild(codeText, 0);
      visit(code);
    }

    @Override
    public void visit(Text node) {
      if (spyOnText) {
        if (node.getValue() != null) {
          text.append(node.getValue());
        }
      }
      super.visit(node);
    }
  }

  /**
   * Used to look up Artifacts in the remote repository.
   *
   * @component
   * @required
   * @readonly
   */
  protected ArtifactResolver artifactResolver;

  /**
   * Used to look up Artifacts in the remote repository.
   *
   * @component
   * @required
   * @readonly
   */
  protected ArtifactFactory factory;

  /**
   * Location of the local repository.
   *
   * @parameter expression="${localRepository}"
   * @readonly
   * @required
   */
  protected ArtifactRepository localRepository;

  /**
   * List of Remote Repositories to be used by the resolver.
   *
   * @parameter expression="${project.remoteArtifactRepositories}"
   * @readonly
   * @required
   */
  @SuppressWarnings("rawtypes")
  protected List remoteRepositories;

  /**
   * Used to look up Artifacts in the remote repository.
   *
   * @component
   * @required
   * @readonly
   */
  protected ArtifactMetadataSource source;

  /**
   * A source directory for extra files to add to the api documentation. If this directory exists,
   * its contents will be included in the generated apidoc.
   *
   * @parameter default-value="${basedir}/src/main/apidoc"
   */
  private File apidocDirectory;

  /**
   * The name of the Doclet to execute.
   *
   * @parameter default-value="com.getperka.flatpack.doclets.DocStringsDoclet"
   * @required
   */
  private String docletClass;

  /**
   * @component
   * @required
   * @readonly
   */
  private BuildContext buildContext;

  /**
   * The destination directory for the generated documentation.
   *
   * @parameter default-value="${project.build.directory}/apidoc"
   */
  private File outputDirectory;

  /**
   * @parameter default-value="${project}"
   * @readonly
   * @required
   */
  private MavenProject project;

  /**
   * The source directory for the java source files. This path will be used to supply the javadoc
   * tool's input.
   *
   * @parameter default-value="${basedir}/src/main/java"
   */
  private File sourceDirectory;

  /**
   * The packages over which the doclet should be executed.
   *
   * @parameter
   * @required
   */
  private String subpackages;

  private static final Charset UTF8 = Charset.forName("UTF-8");

  @Override
  public void execute() throws MojoExecutionException, MojoFailureException {
    if (!buildContext.isIncremental()) {
      extractDocStrings();
    }

    convertMarkdown();
  }

  private void convertMarkdown() {
    if (!apidocDirectory.isDirectory()) {
      return;
    }

    // The directory that the html and resources are emitted into
    File apidocOutputDir = new File(outputDirectory, "apidoc");

    // Copy random resources
    Scanner copyScanner = buildContext.newScanner(apidocDirectory, true);
    copyScanner.setExcludes(new String[] { "apidoc_template.html", "**/*.md" });
    copyScanner.scan();
    for (String copyPath : copyScanner.getIncludedFiles()) {
      File copyFrom = new File(apidocDirectory, copyPath);
      File outFile = new File(apidocOutputDir, copyPath);
      if (buildContext.isUptodate(outFile, copyFrom)) {
        continue;
      }
      try {
        InputStream in = new FileInputStream(copyFrom);
        outFile.getParentFile().mkdirs();
        OutputStream out = buildContext.newFileOutputStream(outFile);
        IOUtil.copy(in, out);
        in.close();
        out.close();
      } catch (IOException e) {
        buildContext.addMessage(copyFrom, 0, 0, "Could not copy resource",
            BuildContext.SEVERITY_ERROR, e);
      }
    }

    // Look for all changed *.md files
    Scanner inputScanner = buildContext.newScanner(apidocDirectory, false);
    inputScanner.setIncludes(new String[] { "**/*.md" });
    inputScanner.scan();
    String[] dirtyPaths = inputScanner.getIncludedFiles();
    if (dirtyPaths.length == 0) {
      return;
    }

    apidocOutputDir.mkdirs();

    // Get the manifest from a previous run
    @SuppressWarnings("unchecked")
    // A map of file paths to titles
    Map<String, String> manifest = (Map<String, String>) buildContext.getValue("manifestMap");
    if (manifest == null) {
      manifest = new TreeMap<String, String>();
      buildContext.setValue("manifestMap", manifest);
    }

    for (String relativePath : dirtyPaths) {
      File mdFile = new File(apidocDirectory, relativePath);
      try {
        Reader in = new InputStreamReader(new FileInputStream(mdFile), UTF8);

        String relativeFragmentPath = relativePath.substring(0,
            relativePath.lastIndexOf('.')) + ".htmlf";
        File outFile = new File(apidocOutputDir, relativeFragmentPath);

        // Make sure the parent diretory exists
        outFile.getParentFile().mkdirs();
        Writer out = new OutputStreamWriter(buildContext.newFileOutputStream(outFile), UTF8);

        Parser parser = new Parser(in);
        TitleSpyHtmlEmitter emitter = new TitleSpyHtmlEmitter(out);
        Document document = parser.parse();
        document.accept(emitter);

        in.close();
        out.close();

        manifest.put(relativeFragmentPath, emitter.getTitle());
      } catch (ParseException e) {
        buildContext.addMessage(mdFile, 0, 0, "Could not parse markdown",
            BuildContext.SEVERITY_ERROR, e);
      } catch (Exception e) {
        buildContext.addMessage(mdFile, 1, 0, "Error processing file", BuildContext.SEVERITY_ERROR,
            e);
      }
    }

    // Write a simple manifest file of all fragments
    try {
      File manifestFile = new File(apidocOutputDir, "manifest");
      JsonWriter writer = new JsonWriter(new OutputStreamWriter(
          buildContext.newFileOutputStream(manifestFile), UTF8));
      writer.beginObject();
      for (Map.Entry<String, String> entry : manifest.entrySet()) {
        writer.name(entry.getKey());
        writer.value(entry.getValue());
      }
      writer.endObject();
      writer.close();
    } catch (Exception e) {
      buildContext.addMessage(apidocDirectory, 0, 0, "Colud not generate manifest",
          BuildContext.SEVERITY_ERROR, e);
    }
  }

  @SuppressWarnings({ "restriction", "unchecked" })
  private void extractDocStrings() throws MojoFailureException {
    Artifact jar = factory.createArtifact(project.getGroupId(), project.getArtifactId(),
        project.getVersion(), "compile", "jar");
    Set<Artifact> artifacts;
    try {
      ArtifactResolutionResult res = artifactResolver.resolveTransitively(
          project.getDependencyArtifacts(),
          jar, remoteRepositories,
          localRepository, source);
      artifacts = res.getArtifacts();
    } catch (ArtifactNotFoundException e) {
      throw new MojoFailureException("Could not resolve jar", e);
    } catch (ArtifactResolutionException e) {
      throw new MojoFailureException("Could not resolve jar", e);
    }
    getLog().debug("Resolved " + artifacts.toString());
    List<String> args = new ArrayList<String>();

    StringBuilder sb = new StringBuilder();
    for (Artifact a : artifacts) {
      sb.append(File.pathSeparatorChar).append(a.getFile().getAbsolutePath());
    }

    args.add("-classpath");
    args.add(sb.substring(1));
    args.add("-doclet");
    args.add(docletClass);
    args.add("-sourcepath");
    args.add(sourceDirectory.getAbsolutePath());
    args.add("-subpackages");
    args.add(subpackages);
    args.add("-d");
    args.add(outputDirectory.getAbsolutePath());

    int ret = com.sun.tools.javadoc.Main.execute(args.toArray(new String[args.size()]));
    if (ret != 0) {
      throw new MojoFailureException("Javadoc tool returned status code " + ret);
    }

    Resource resource = new Resource();
    resource.setDirectory(outputDirectory.getPath());
    project.addResource(resource);

    buildContext.refresh(outputDirectory);
  }

  private File findPackageJson(String className) {
    String packageName = className.substring(0, className.lastIndexOf('.'));

    while (!packageName.isEmpty()) {
      File f = new File(outputDirectory, packageName.replace('.', '/') + "/package.json");
      if (f.canRead()) {
        return f;
      }
      int idx = packageName.lastIndexOf('.');
      if (idx == -1) {
        break;
      }
      packageName = packageName.substring(0, idx);
    }
    return null;
  }
}