| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <title>Tooling - CLI :: Apache Isis</title> |
| <link rel="canonical" href="https://isis.apache.org/tooling/2.0.0-M6/tooling-cli/about.html"> |
| <meta name="generator" content="Antora 2.3.4"> |
| <link rel="stylesheet" href="../../../_/css/site.css"> |
| <link rel="stylesheet" href="../../../_/css/site-custom.css"> |
| <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,700,700i|Raleway:300,400,500,700,800|Montserrat:300,400,700" rel="stylesheet"> |
| <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"/> |
| <link rel="home" href="https://isis.apache.org" title="Apache Isis"> |
| <link rel="prev" href="../about.html" title="Tooling"> |
| </head> |
| <body class="article"> |
| <header class="header"> |
| <nav class="navbar"> |
| <div class="navbar-brand"> |
| <a class="navbar-item" href="https://isis.apache.org"> |
| <span class="icon"> |
| <img src="../../../_/img/isis-logo-48x48.png"></img> |
| </span> |
| <span>Apache Isis</span> |
| </a> |
| <button class="navbar-burger" data-target="topbar-nav"> |
| <span></span> |
| <span></span> |
| <span></span> |
| </button> |
| </div> |
| <div id="topbar-nav" class="navbar-menu"> |
| <a class="navbar-end"> |
| <div class="navbar-item hide-for-print"> |
| <span> |
| <input id="algolia-search-input" placeholder="Search"></span> |
| </span> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Quick Start</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Starter Apps</span> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/starters/helloworld.html">Hello World</a> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/starters/simpleapp.html">Simple App</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Demos & Tutorials</span> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/demo/about.html">Demo App</a> |
| <a class="navbar-item" href="https://danhaywood.gitlab.io/isis-petclinic-tutorial-docs/petclinic/1.16.2/intro.html">Petclinic (tutorial)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Resources</span> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/resources/cheatsheet.html">Cheatsheet</a> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/resources/icons.html">Icons</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Guides</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Development</span> |
| <a class="navbar-item" href="../../../setupguide/2.0.0-M6/about.html">Setup Guide</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Core</span> |
| <a class="navbar-item" href="../../../userguide/2.0.0-M6/about.html">User Guide</a> |
| <a class="navbar-item" href="../../../refguide/2.0.0-M6/about.html">Reference Guide</a> |
| <a class="navbar-item" href="../../../testing/2.0.0-M6/about.html">Testing Guide</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Components</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Viewers</span> |
| <a class="navbar-item" href="../../../vw/2.0.0-M6/about.html">Web UI (Wicket)</a> |
| <a class="navbar-item" href="../../../vro/2.0.0-M6/about.html">REST API (Restful Objects)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Persistence</span> |
| <a class="navbar-item" href="../../../pjpa/2.0.0-M6/about.html">JPA (EclipseLink)</a> |
| <a class="navbar-item" href="../../../pjdo/2.0.0-M6/about.html">JDO (DataNucleus)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Security</span> |
| <a class="navbar-item" href="../../../security/2.0.0-M6/about.html">Security Guide</a> |
| <hr class="navbar-divider"/> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Libraries</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">For Use in Apps</span> |
| <a class="navbar-item" href="../../../subdomains/2.0.0-M6/about.html">Subdomain Libraries</a> |
| <a class="navbar-item" href="../../../valuetypes/2.0.0-M6/about.html">Value Type Catalog</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Integrate between Apps</span> |
| <a class="navbar-item" href="../../../mappings/2.0.0-M6/about.html">Bounded Context Mapping Libraries</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Extending the framework itself</span> |
| <a class="navbar-item" href="../../../extensions/2.0.0-M6/about.html">Extensions Catalog</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Support</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Contact</span> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/support/slack-channel.html">Slack</a> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/support/mailing-list.html">Mailing Lists</a> |
| <a class="navbar-item" href="https://issues.apache.org/jira/browse/ISIS">JIRA</a> |
| <a class="navbar-item" href="https://stackoverflow.com/questions/tagged/isis">Stack Overflow</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Releases</span> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/downloads/how-to.html">Downloads</a> |
| <a class="navbar-item" href="../../../relnotes/2.0.0-M6/about.html">Release Notes</a> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/archive/1-x.html">Archive (1.x)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Framework</span> |
| <a class="navbar-item" href="../../../conguide/2.0.0-M6/about.html">Contributors' Guide</a> |
| <a class="navbar-item" href="../../../comguide/2.0.0-M6/about.html">Committers' Guide</a> |
| <a class="navbar-item" href="../../../core/2.0.0-M6/about.html">Core Design</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">ASF</a> |
| <div class="navbar-dropdown"> |
| <a class="navbar-item" href="http://www.apache.org/">Apache Homepage</a> |
| <a class="navbar-item" href="https://www.apache.org/events/current-event">Events</a> |
| <a class="navbar-item" href="https://www.apache.org/licenses/">Licenses</a> |
| <a class="navbar-item" href="https://www.apache.org/security/">Security</a> |
| <a class="navbar-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="navbar-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| <hr class="navbar-divider"/> |
| <a class="navbar-item" href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a> |
| </div> |
| </div> |
| <a class="navbar-item" href="../../../docs/2.0.0-M6/about.html"> |
| <span class="icon"> |
| <img src="../../../_/img/home.png"></img> |
| </span> |
| </a> |
| </div> |
| </div> |
| </nav> |
| </header> |
| <div class="body "> |
| <div class="nav-container" data-component="tooling" data-version="2.0.0-M6"> |
| <aside class="nav"> |
| <div class="panels"> |
| <div class="nav-panel-pagination"> |
| <a class="page-previous" rel="prev" href="../about.html" title="Tooling"><span></span></a> |
| <a class="page-next disabled" rel="next" |
| href="" title=""><span></span></a> |
| <!-- |
| page.parent doesn't seem to be set... |
| <a class="page-parent disabled" rel="prev" href="" title="Tooling"><span></span></a> |
| --> |
| </div> |
| <div class="nav-panel-menu is-active" data-panel="menu"> |
| <nav class="nav-menu"> |
| <h3 class="title"><a href="../about.html">Tooling</a></h3> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item is-current-page" data-depth="1"> |
| <a class="nav-link" href="about.html">Tooling CLI</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </div> |
| <div class="nav-panel-explore" data-panel="explore"> |
| <div class="context"> |
| <span class="title">Tooling</span> |
| <span class="version">2.0.0-M6</span> |
| </div> |
| <ul class="components"> |
| <li class="component"> |
| <span class="title"> </span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../docs/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../docs/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">BC Mapping Libraries</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../mappings/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../mappings/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Committers' Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../comguide/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../comguide/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Contributors' Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../conguide/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../conguide/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Design Docs</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../core/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../core/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Extensions Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../extensions/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../extensions/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Incubator Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../incubator/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../incubator/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">JDO/DataNucleus</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../pjdo/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../pjdo/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">JPA</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../pjpa/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../pjpa/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Reference Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../refguide/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../refguide/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Release Notes</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../relnotes/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../relnotes/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">REST API (Restful Objects Viewer)</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../vro/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../vro/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Security Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../security/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../security/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Setup Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../setupguide/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../setupguide/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Subdomains Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../subdomains/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../subdomains/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Testing Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../testing/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../testing/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component is-current"> |
| <span class="title">Tooling</span> |
| <ul class="versions"> |
| <li class="version is-current is-latest"> |
| <a href="../about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">User Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../userguide/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../userguide/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Value Types Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../valuetypes/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../valuetypes/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Web UI (Wicket Viewer)</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../vw/2.0.0-M6/about.html">2.0.0-M6</a> |
| </li> |
| <li class="version"> |
| <a href="../../../vw/2.0.0-M5/about.html">2.0.0-M5</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </aside> |
| </div> |
| <main role="main"> |
| <div class="toolbar" role="navigation"> |
| <button class="nav-toggle"></button> |
| <a href="../../../docs/2.0.0-M6/about.html" class="home-link"></a> |
| <nav class="breadcrumbs" aria-label="breadcrumbs"> |
| <ul> |
| <li><a href="../about.html">Tooling</a></li> |
| <li><a href="about.html">Tooling CLI</a></li> |
| </ul> |
| </nav> |
| <div class="page-versions"> |
| <button class="version-menu-toggle" title="Show other versions of page">2.0.0-M6</button> |
| <div class="version-menu"> |
| <a class="version is-current" href="about.html">2.0.0-M6</a> |
| <a class="version" href="../../2.0.0-M5/tooling-cli/about.html">2.0.0-M5</a> |
| </div> |
| </div> |
| <div class="edit-this-page"><a href="https://github.com/apache/isis/edit/2.0.0-M6/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc">Edit</a></div> |
| </div> |
| <article class="doc"> |
| <a name="section-top"></a> |
| <h1 class="page">Tooling - CLI</h1> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Command Line Interface for the <em>Apache Isis Tooling</em> ecosystem, to generate documentation from program sources (<code>.java</code> files, <code>pom.xml</code>, etc).</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="prerequisites"><a class="anchor" href="#prerequisites"></a>Prerequisites</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>From the root of the git repo, build the tooling using Java 11:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">mvn install -D module-tooling -Dskip.essential</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will generate the command line CLI as an executable jar in its target directory (<code>tooling/cli/target</code>).</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="available-commands"><a class="anchor" href="#available-commands"></a>Available Commands</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Use the help command to see a list of available commands:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">calling for help</div> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code>java -jar tooling/cli/target/isis-tooling-cli.jar --help</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>which (currently) generates the following:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code>Usage: cli [-hV] [-o=<outputPath>] [-p=<projectRootPath>] [COMMAND] |
| CLI for the Apache Isis Tooling Ecosystem |
| -h, --help Show this help message and exit. |
| -w, --overview=<overviewPath> |
| path to write the overview file (default: NONE = write to std.out) |
| -x, --index=<indexPath> |
| path to write the refguide index files (default: NONE = write to std.out) |
| -p, --project=<projectRootPath> |
| path to the (multi-module) project root (default: current dir) |
| -V, --version Print version information and exit. |
| Commands: |
| projdoc Writes all generated (AsciiDoc) to given output. |
| overview Writes a System Overview document (AsciiDoc) to given output. |
| index Writes a Global Index (AsciiDoc) to given output.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The "projdoc" command is the usual command to use, as it performs both the "overview" and "index" commands.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By default, the current directory is used as the target to perform commands in.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="configuration-file"><a class="anchor" href="#configuration-file"></a>Configuration File</h3> |
| <div class="paragraph"> |
| <p>The <code>isis-tooling.yml</code> configuration file (found in the root of the repo) provides default options for each command, as well as global defaults applicable to all commands:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">isis-tooling.yml</div> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">global: <i class="conum" data-value="1"></i><b>(1)</b> |
| option ... |
| option ... |
| command: |
| overview: <i class="conum" data-value="2"></i><b>(2)</b> |
| option ... |
| option ... |
| ... |
| index: <i class="conum" data-value="3"></i><b>(3)</b> |
| option ... |
| option ... |
| ...</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>configuration applicable to all commands</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>configuration for the "overview" command (also used by the "projdoc" command)</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="3"></i><b>3</b></td> |
| <td>configuration for the "index" command (also used by the "projdoc" command)</td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| This configuration file is mapped onto the <code>CLIConfig</code> bean. |
| Inspect its <a href="https://github.com/apache/isis/blob/master/tooling/cli/src/main/java/org/apache/isis/tooling/cli/CliConfig.java#L31">source code</a> for more detailed information. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="commands"><a class="anchor" href="#commands"></a>Commands</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>All commands accept the following common parameters:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>-p</code> indicates the location of the multi-project root <code>pom.xml</code></p> |
| <div class="paragraph"> |
| <p>in other words, the root of the git repo.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>A number of global configuration options can be specified under the <code>global</code> entry in the <code>isis-tooling.yml</code> file.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">isis-tooling.yml</div> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">global: |
| licenseHeader: "Licensed to the Apache Software Foundation (ASF) ..." <i class="conum" data-value="1"></i><b>(1)</b></code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>license header to include with each generated adoc file</td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="project-documentation-projdoc"><a class="anchor" href="#project-documentation-projdoc"></a>Project documentation (<code>projdoc</code>)</h3> |
| <div class="paragraph"> |
| <p>This command generates both a <a href="#system-overview-overview">system overview</a> and generates the <a href="#index-index">global index</a>, and as such is the command that you will probably want to use most of the time. |
| See those two commands for further details.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="usage"><a class="anchor" href="#usage"></a>Usage</h4> |
| <div class="paragraph"> |
| <p>The <code>projdoc</code> command is usually invoked as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code>java -jar tooling/cli/target/isis-tooling-cli.jar \ |
| -p . \ |
| -w core/adoc \ |
| -x antora/components/refguide-index \ |
| projdoc</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where :</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>-p</code> is a global options for all commands</p> |
| </li> |
| <li> |
| <p><code>-w</code> is the option for the <code>overview</code> sub-command, specifying the output root path</p> |
| </li> |
| <li> |
| <p><code>-x</code> is the option for the <code>index</code> sub-command</p> |
| </li> |
| <li> |
| <p><code>projdoc</code> selects this sub-command (which simply runs both <code>overview</code> and <code>index</code> sub-commands)</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="projdoc-configuration"><a class="anchor" href="#projdoc-configuration"></a>Configuration</h4> |
| <div class="paragraph"> |
| <p>The <code>projdoc</code> command has no specific configuration. |
| However, as it is effectively just the combination of the <code>overview</code> and <code>index</code> commands, note that those two commands <em>do</em> have their own configuration settings; see <a href="#overview-configuration">overview configuration</a> and <a href="#index-configuration">index configuration</a> respectively.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="system-overview-overview"><a class="anchor" href="#system-overview-overview"></a>System Overview (<code>overview</code>)</h3> |
| <div class="paragraph"> |
| <p>This command generates the <em>System Overview</em> (`.adoc) page.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This page summarises the contents of each section (defined by the <code>commands.overview.sections</code> configuration key), also with a <a href="https://c4model.com/">C4</a> diagram showing how the modules relate.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="usage-2"><a class="anchor" href="#usage-2"></a>Usage</h4> |
| <div class="paragraph"> |
| <p>The <code>overview</code> command is usually invoked as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code>java -jar tooling/cli/target/isis-tooling-cli.jar \ |
| -p . \ |
| -v core/adoc \ |
| overview</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where :</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>-p</code> is a global options for all commands</p> |
| </li> |
| <li> |
| <p><code>-w</code> is the option for the <code>overview</code> sub-command, specifying the output root path</p> |
| </li> |
| <li> |
| <p><code>overview</code> selects this sub-command</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>There are no command-specific options.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="overview-configuration"><a class="anchor" href="#overview-configuration"></a>Configuration</h4> |
| <div class="paragraph"> |
| <p>The <code>overview</code> command supports a number of command-specific configuration options:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">isis-tooling.yml</div> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">commands: |
| overview: |
| rootFolder: <i class="conum" data-value="1"></i><b>(1)</b> |
| pagesPath: "modules/_overview/pages" <i class="conum" data-value="2"></i><b>(2)</b> |
| systemOverviewFilename: "about.adoc" <i class="conum" data-value="3"></i><b>(3)</b> |
| description: "These tables summarize all Maven artifacts ..." <i class="conum" data-value="4"></i><b>(4)</b> |
| sections: <i class="conum" data-value="5"></i><b>(5)</b> |
| ... |
| Persistence: org.apache.isis.persistence |
| JDO: "org.apache.isis.persistence:isis-persistence-jdo.*" |
| JPA: "org.apache.isis.persistence:isis-persistence-jpa.*" |
| ...</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>the output target root for generated overview <em>adoc</em>; corresponds to command line option <code>-v</code> (if empty the current dir is used)</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>sub-folder name for <em>adoc</em> pages</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="3"></i><b>3</b></td> |
| <td>name of the <em>System Overview</em> (adoc) file</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="4"></i><b>4</b></td> |
| <td><em>System Overview</em> summary description text</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="5"></i><b>5</b></td> |
| <td>Logical grouping of modules for the system overview, but also used to determine which modules to scan for index files. |
| <div class="paragraph"> |
| <p>If not specified the natural Maven project hierarchy is reflected as is. |
| This is discussed in more detail below.</p> |
| </div></td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>sections</code> configuration key is used to group module artifacts into named sections. |
| It consists of key:value pairs:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>the key is the section name (eg "App", or "JDO")</p> |
| </li> |
| <li> |
| <p>the value is a pattern that identifies Maven artifacts.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This pattern in turn can be either:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>an exact Maven <code>groupId</code>, such as <code>org.apache.isis.persistence</code></p> |
| <div class="paragraph"> |
| <p>This matches all Maven modules with exactly that <code>groupId</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p>a Maven <code>groupId</code> with wildcard, such as <code>org.apache.isis.core.*</code></p> |
| <div class="paragraph"> |
| <p>This matches all Maven modules whose <code>groupId</code> pattern matches the groupId.</p> |
| </div> |
| </li> |
| <li> |
| <p>a Maven group and artifact optionally with wildcard, such as <code>org.apache.isis.persistence:isis-persistence-jdo.*</code></p> |
| <div class="paragraph"> |
| <p>This matches all Maven modules whose <code>groupId</code> pattern equals the specified groupId and whose <code>artifactId</code> pattern matches the specified <code>artifactId</code>.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If a Maven module matches more than one section, then the more specific section (with both group and artifact) is used.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These different types of sections are exploited by the <code>overview</code> command, described <a href="#system-overview-overview">below</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Sections that match on a groupID are placed under a level 2 heading, while sections matching on group and artifact are placed under a level 3 heading. |
| By sequencing the sections correctly, this therefore allows a hierarchy to be created.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, in the config example above the sections defined will render "Persistence" section at level 2 (because its pattern is only for a <code>groupId</code>), and then the "JDO" and "JPA" sections underneath at level 3 (because there patterns also include an <code>artifactId</code>).</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="index-index"><a class="anchor" href="#index-index"></a>Index (<code>index</code>)</h3> |
| <div class="paragraph"> |
| <p>This command generates the <em>Document Global Index</em> (<code>.adoc</code>) files.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Any class found with magic <code>{@index}</code> in its <em>java-doc</em> section at type level, will be included with the <em>Document Global Index</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Asciidoc files may refer to the <em>Document Global Index</em> via <code>xref</code> or <code>include</code> statements using paths such as <code>refguide:applib:index/annotation/Xxx.adoc</code>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="usage-3"><a class="anchor" href="#usage-3"></a>Usage</h4> |
| <div class="paragraph"> |
| <p>The <code>index</code> command is usually invoked as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code>java -jar tooling/cli/target/isis-tooling-cli.jar \ |
| -p . \ |
| -x antora/components/refguide-index \ |
| index</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where :</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>-p</code> is a global options for all commands</p> |
| </li> |
| <li> |
| <p><code>-x</code> is the option for the <code>index</code> sub-command, specifying the output root path</p> |
| </li> |
| <li> |
| <p><code>index</code> selects this sub-command</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="index-configuration"><a class="anchor" href="#index-configuration"></a>Configuration</h4> |
| <div class="paragraph"> |
| <p>The <code>index</code> command supports a number of command-specific configuration options:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">isis-tooling.yml</div> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">commands: |
| index: |
| rootFolder: <i class="conum" data-value="1"></i><b>(1)</b> |
| documentGlobalIndexPath: "pages/index" <i class="conum" data-value="2"></i><b>(2)</b> |
| documentGlobalIndexXrefPageIdFormat: "system:generated:index/%s.adoc" <i class="conum" data-value="3"></i><b>(3)</b> |
| namespacePartsSkipCount: 3 <i class="conum" data-value="4"></i><b>(4)</b> |
| fixOrphanedAdocIncludeStatements: true <i class="conum" data-value="5"></i><b>(5)</b></code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>the output target root for generated index <em>adoc</em> files; corresponds to command line option <code>-x</code> (if empty the current dir is used)</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>sub-folder name for the <em>Document Global Index</em></td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="3"></i><b>3</b></td> |
| <td>format for include statements via which other <em>adoc</em> files may refer to the Document Global Index</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="4"></i><b>4</b></td> |
| <td>how many namespace parts in a <em>fqn</em> one wants to skip, eg. in <code>org.apache.isis.applib.Xxx</code> if we skip 3 namespace parts we’ll end up with <code>applib.Xxx</code></td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="5"></i><b>5</b></td> |
| <td>whether to activate the <code>OrphanedIncludeStatementFixer</code>.</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The CLI also has an experimental <code>OrphanedIncludeStatementFixer</code> that checks orphaned index references in all <em>adoc</em> files and tries to fix them.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="limitations"><a class="anchor" href="#limitations"></a>Limitations</h4> |
| <div class="paragraph"> |
| <p>There are currently a couple of limitations:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>the <em>Document Global Index</em> can only contain classes unique by their simple name, otherwise the <code>OrphanedIncludeStatementFixer</code> would not be able to reason about how to fix orphaned references.</p> |
| </li> |
| <li> |
| <p>the <code>OrphanedIncludeStatementFixer</code> also can fix up references to classes that have been moved, but it cannot fix up orphans where the class has been renamed.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </article> |
| <aside class="article-aside toc hide-for-print" role="navigation"> |
| <p class="toc-title">On this page</p> |
| <div id="article-toc"></div> |
| </aside> |
| </main> |
| </div> |
| <footer class="footer"> |
| <div class="content"> |
| <div class="copyright"> |
| <p> |
| Copyright © 2010~2021 The Apache Software Foundation, licensed under the Apache License, v2.0. |
| <br/> |
| Apache, the Apache feather logo, Apache Isis, and the Apache Isis project logo are all trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| <div class="revision"> |
| <p>Revision: release-2.0.0-M6-RC2.20210826-0110</p> |
| </div> |
| </div> |
| </footer> |
| <script src="../../../_/js/site.js"></script> |
| <script async src="../../../_/js/vendor/highlight.js"></script> |
| <script src="../../../_/js/vendor/jquery-3.4.1.min.js"></script> |
| <script src="../../../_/js/vendor/jquery-ui-1.12.1.custom.widget-only.min.js"></script> |
| <script src="../../../_/js/vendor/jquery.tocify.min.js"></script> |
| |
| <script> |
| $(function() { |
| $("#article-toc").tocify( { |
| showEffect: "slideDown", |
| hashGenerator: "pretty", |
| hideEffect: "slideUp", |
| selectors: "h2, h3", |
| scrollTo: 120, |
| smoothScroll: true, |
| theme: "jqueryui", |
| highlightOnScroll: true |
| } ); |
| }); |
| </script> |
| |
| <script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script> |
| <script> |
| function focusSearchInput () { document.querySelector('#algolia-search-input').focus() } |
| var search = docsearch({ |
| appId: '5ISP5TFAEN', |
| apiKey: '0fc51c28b4ad46e7318e96d4e97fab7c', |
| indexName: 'isis-apache-org', |
| inputSelector: '#algolia-search-input', |
| autocompleteOptions: { hint: false, keyboardShortcuts: ['s'] }, |
| debug: false, |
| }).autocomplete |
| search.on('autocomplete:closed', function () { search.autocomplete.setVal() }) |
| focusSearchInput() |
| window.addEventListener('load', focusSearchInput); |
| </script> |
| |
| <!-- |
| docsearch options: |
| https://docsearch.algolia.com/docs/behavior/ |
| --> |
| <!-- |
| https://www.algolia.com/doc/api-reference/api-parameters/ |
| algoliaOptions: { hitsPerPage: 6 }, |
| --> |
| </body> |
| </html> |
