Class DocGenerator

java.lang.Object
net.simplace.core.doc.DocGenerator

public class DocGenerator extends Object
Creates the javadoc of SIMPLACE source trees with the documentation of the SimComponents and resource transformers, independently of a build tool (console, HPC, Eclipse launch configuration, ant, Maven, ...).

Steps:

  1. The source trees are copied to a work directory; in the copy the doc comments are prepared by the CommentPreprocessor: wiki text converted to HTML (WikiConverter) and the variable table appended to the class comment of every SimComponent and transformer (VariableTable). The original sources are not changed.
  2. An overview page with all SimComponents and transformers is written (javadoc option -overview).
  3. The standard javadoc tool is called (via ToolProvider.getSystemDocumentationTool()) with the prepared sources, the stylesheet and the scripts for MathJax and sortable tables (--add-stylesheet, --add-script). The generated pages are not changed afterwards.
The classes of the source trees must be compiled and on the class path, because the components are instantiated to create their variables. The class path is also passed to javadoc.

Call: java -cp <class path> net.simplace.core.doc.DocGenerator --source <dir> [--source <dir> ...] --out <dir> [options] [-- <further javadoc options>], see main(String[]).

Author:
Andreas Enders
  • Field Details

    • DEFAULT_MATHJAX_URL

      public static final String DEFAULT_MATHJAX_URL
      default MathJax script (local copy on simplace.net, MathJax 2)
      See Also:
    • FALLBACK_MATHJAX_URL

      public static final String FALLBACK_MATHJAX_URL
      MathJax used if the pages are opened locally or the configured script cannot be loaded (MathJax 3, CDN)
      See Also:
  • Constructor Details

    • DocGenerator

      public DocGenerator()
  • Method Details

    • main

      public static void main(String[] args)
      Runs the generator.

      Options:

      • --source <dir> source directory (repeatable, e.g. src and conf)
      • --out <dir> output directory of the documentation
      • --work <dir> work directory for the prepared sources (default: <out>_work, deleted and created again)
      • --title <text> window and document title
      • --overview <file> own overview page instead of the generated SimComponent overview
      • --mathjax <url> MathJax script (default DEFAULT_MATHJAX_URL; a MathJax 3 URL, e.g. https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js, gets the MathJax 3 configuration; opened locally or if not loadable, FALLBACK_MATHJAX_URL is used)
      • --header <html> header text of each page (javadoc -header), e.g. the script of the web site
      • --bottom <html> bottom text of each page (default: creation time); {NOW} is replaced by the creation time
      • -- ... all following arguments are passed to javadoc
      Parameters:
      args - the options
    • createMathJaxScript

      public static String createMathJaxScript(String aMathJaxUrl)
      Creates the script that configures and loads MathJax, see writeMathJaxScript(File).
      Parameters:
      aMathJaxUrl - URL of the MathJax script
      Returns:
      the JavaScript code
    • readResource

      public static String readResource(String aName) throws IOException
      Reads a stylesheet or script from the class path (folder doc/, in simplace_core res/files/doc).
      Parameters:
      aName - file name, e.g. simplace-doc.css
      Returns:
      the content
      Throws:
      IOException - if the resource is missing or cannot be read