You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nlpcraft.apache.org by ar...@apache.org on 2021/01/04 19:38:19 UTC
[incubator-nlpcraft-website] branch master updated: Refactored
nlpcraft.sh script docs.
This is an automated email from the ASF dual-hosted git repository.
aradzinski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nlpcraft-website.git
The following commit(s) were added to refs/heads/master by this push:
new 5b3258f Refactored nlpcraft.sh script docs.
5b3258f is described below
commit 5b3258fc3b8f67ac13d70fd557b1d639594b1db8
Author: Aaron Radzinski <ar...@datalingvo.com>
AuthorDate: Mon Jan 4 11:38:09 2021 -0800
Refactored nlpcraft.sh script docs.
---
_layouts/default.html | 29 ++++----
media/nlpcraft_logo.psd | Bin 180345 -> 0 bytes
media/nlpcraft_logo_black.gif | Bin 14277 -> 0 bytes
media/nlpcraft_logo_white.gif | Bin 6019 -> 0 bytes
tools/script.html | 157 ++++++++++++------------------------------
5 files changed, 58 insertions(+), 128 deletions(-)
diff --git a/_layouts/default.html b/_layouts/default.html
index 52d573a..58c59c8 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -57,8 +57,8 @@ layout: compress
<script src="//stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script> <!-- BS3 CSS, etc. -->
<link href="//use.fontawesome.com/releases/v5.7.1/css/all.css" integrity="sha384-fnmOCqbTlWIlj8LyTjo7mOUStjsKC4pOpQbqyi7RrhN7udi9RwhKkMHpvLbHG9Sr" rel="stylesheet" crossorigin="anonymous">
- <link href="{{ '/ext/syntaxhighlighter/styles/shCoreNLPCraft.css' | relative_url }}" rel="stylesheet" type="text/css">
- <link href="{{ '/ext/syntaxhighlighter/styles/shThemeNLPCraft.css' | relative_url }}" rel="stylesheet" type="text/css">
+ <link href="/ext/syntaxhighlighter/styles/shCoreNLPCraft.css" rel="stylesheet" type="text/css">
+ <link href="/ext/syntaxhighlighter/styles/shThemeNLPCraft.css" rel="stylesheet" type="text/css">
<!-- Google fonts. -->
<link rel="preconnect" href="https://fonts.gstatic.com">
@@ -66,18 +66,19 @@ layout: compress
<link href="//fonts.googleapis.com/css2?family=Libre+Baskerville:ital@1&display=swap" rel="stylesheet">
<!-- Loading some init libs here. -->
- <script src="{{ '/ext/syntaxhighlighter/scripts/XRegExp.js' | relative_url }}" type="text/javascript"></script>
- <script src="{{ '/ext/syntaxhighlighter/scripts/shCore.js' | relative_url }}" type="text/javascript"></script>
- <script src="{{ '/ext/syntaxhighlighter/scripts/shBrushXml.js' | relative_url }}" type="text/javascript"></script>
- <script src="{{ '/ext/syntaxhighlighter/scripts/shBrushPlain.js' | relative_url }}" type="text/javascript"></script>
- <script src="{{ '/ext/syntaxhighlighter/scripts/shBrushJava.js' | relative_url }}" type="text/javascript"></script>
- <script src="{{ '/ext/syntaxhighlighter/scripts/shBrushScala.js' | relative_url }}" type="text/javascript"></script>
- <script src="{{ '/ext/syntaxhighlighter/scripts/shBrushPython.js' | relative_url }}" type="text/javascript"></script>
- <script src="{{ '/ext/syntaxhighlighter/scripts/shBrushJScript.js' | relative_url }}" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/XRegExp.js" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shCore.js" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shBrushXml.js" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shBrushBash.js" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shBrushPlain.js" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shBrushJava.js" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shBrushScala.js" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shBrushPython.js" type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shBrushJScript.js" type="text/javascript"></script>
<script async defer src="https://buttons.github.io/buttons.js"></script>
<!-- Main CSS. -->
- <link rel="stylesheet" type="text/css" href="{{ '/assets/css/style.css' | relative_url }}"/>
+ <link rel="stylesheet" type="text/css" href="/assets/css/style.css"/>
<!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
@@ -90,7 +91,7 @@ layout: compress
<!-- Fixed navbar -->
<nav class="navbar navbar-expand-lg navbar-light bg-light" id="top-header">
<a class="navbar-brand mr-4" href="/index.html">
- <img src="{{ 'images/nlpcraft_logo_white.gif' | relative_url }}" height="24px">
+ <img src="/images/nlpcraft_logo_white.gif" height="24px">
</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
@@ -123,7 +124,7 @@ layout: compress
<a class="nav-link" href="/download.html">v.{{ site.latest_version}}</a>
</li>
<li class="nav-item">
- <a class="nav-link fork-link" target="github" href="https://github.com/apache/incubator-nlpcraft">GitHub <img height="20px" src="{{ 'images/github_logo_white.png' | relative_url }}"></a>
+ <a class="nav-link fork-link" target="github" href="https://github.com/apache/incubator-nlpcraft">GitHub <img height="20px" src="/images/github_logo_white.png"></a>
</li>
</ul>
</div>
@@ -136,7 +137,7 @@ layout: compress
<div class="text-muted text-center">
<span>Copyright © 2021 Apache Software Foundation</span>
<span>
- <a target=_new href="https://apache.org"><img alt="asf" src="{{ '/images/asf_logo.png' | relative_url }}" height="24px"></a>
+ <a target=_new href="https://apache.org"><img alt="asf" src="/images/asf_logo.png" height="24px"></a>
</span>
<a target="asf" href="https://www.apache.org/events/current-event.html" class="btn btn-link ml-4">Events</a>
<span class="sep">•</span>
diff --git a/media/nlpcraft_logo.psd b/media/nlpcraft_logo.psd
deleted file mode 100644
index df8f249..0000000
Binary files a/media/nlpcraft_logo.psd and /dev/null differ
diff --git a/media/nlpcraft_logo_black.gif b/media/nlpcraft_logo_black.gif
deleted file mode 100644
index bc1a1f2..0000000
Binary files a/media/nlpcraft_logo_black.gif and /dev/null differ
diff --git a/media/nlpcraft_logo_white.gif b/media/nlpcraft_logo_white.gif
deleted file mode 100644
index 59d7bf9..0000000
Binary files a/media/nlpcraft_logo_white.gif and /dev/null differ
diff --git a/tools/script.html b/tools/script.html
index e672745..3f9f2bf 100644
--- a/tools/script.html
+++ b/tools/script.html
@@ -147,129 +147,58 @@ id: script
as well.
</p>
</section>
- <section id="usage">
- <h2 class="section-title">Usage</h2>
+ <section id="tips">
+ <h2 class="tips">Tips <span class="amp">&</span> Tricks</h2>
<p>
- Commands supported by the <code>bin/nlpcraft.{sh|cmd}</code> script fall into 4 categories:
+ <code>bin/nlpcraft.{sh|cmd}</code> is standard command line utility that can be used in the familiar ways both in
+ Linux/Unix and Window environments. Note that only Windows 10 has been tested.
</p>
- <ol>
+ <h2 class="section-sub-title">Using <code>start-server</code> Command</h2>
+ <p>
+ REST server is a fire-and-forget component in NLPCraft. You can start it once and you only need to restart it
+ if you change the server configuration. It is customary to add <code>bin/nlpcraft.{sh|cmd} start-server</code>
+ call to the OS init script to have it started automatically on boot up.
+ </p>
+ <h2 class="section-sub-title">Using Default <code>nlpcraft.conf</code></h2>
+ <p>
+ It is recommended to modify the standard <code>nlpcraft.conf</code> configuration file (i.e. <em>in a standard
+ installation location</em>). Commands like <code>start-server</code>, <code>start-probe</code> and
+ <code>test-model</code> use this default location by default and you will not have to specify alternative
+ location or provide other overrides every time you run these commands.
+ </p>
+ <p>
+ If you keep all your configuration modifications in the standard <code>nlpcraft.conf</code> file you can simply
+ run these commands without any additional arguments - significantly simplifying their usage.
+ </p>
+ <h2 class="section-sub-title">Using <code>bin/nlpcraft.{sh|cmd}</code> In Scripts</h2>
+ <p>
+ All of the commands that utilize REST API produce JSON responses. You can easily parse these JSON responses
+ for your own needs in your scripts. For example, here's the code to get the access token from the <code>signin</code>
+ command (on Linux):
+ </p>
+ <pre class="brush: bash">
+ $ bin/nlpcraft.sh no-ansi no-logo signin --email=admin@admin.com --passwd=admin | tail -n +2 | jq -M '.acsTok' | tr -d '"'
+ kkoXBAn8yruEzXrj8Kja5
+ </pre>
+ <p>
+ <b>NOTES:</b>
+ </p>
+ <ul>
<li>
- <b>Server Commands.</b><br/>
- <p>
- Server commands allow to manage locally run REST server. Note that these commands only work for the REST
- server that runs on the same host as script. In other words, these commands cannot manage the remote REST
- server.
- </p>
- <p>
- REST server is a "fire-and-forget" component. During model development you will likely start the
- server only once and check its output from time to time as most of the work will be happening in the data probe
- that hosts your models.
- </p>
- <p>
- For example, <code>start-server</code> command provide the easiest and quickest way to start the REST server (with
- default configuration by default):
- </p>
- <p>
- <img class="non-fluid-img" alt="" src="/images/cli3.png">
- </p>
- <p>
- Note that when <code>start-server</code> commands completes it shows all connected probes (none in this example)
- and automatically signs in with the default <code>admin@admin.com</code> user account so that you can proceed
- to testing and working with your model right away.
- </p>
- <div class="bq info">
- <b>REPL Prompt</b>
- <p>
- REPL prompt shows 3 pieces of information:
- </p>
- <ul>
- <li>REST server status (<code>ON</code> if server is started and detected, <code>OFF</code> otherwise).</li>
- <li>REST access token if the user is signed in. This token is required for all REST calls.</li>
- <li>Current user working directory.</li>
- </ul>
- </div>
+ We use <code>no-ansi</code> and <code>no-logo</code> special commands that clean up and simplify the
+ output so that it would be easier to parse the resulting JSON.
</li>
<li>
- <b>REST Commands:</b>
- <p>
- All REST commands provide convenient wrappers for <a href="/using-rest.html">REST API</a>.
- </p>
- <p>
- Tha two main commands are <code>call</code> and <code>rest</code> - they provide generic REST call wrapper
- for both REPL and command line modes respectively. <code>call</code> command is convenient for the REPL
- mode, while <code>rest</code> command is more convenient for the command line mode.
- </p>
- <p>
- Following additional commands provide custom wrappers for frequently used REST APIs:
- </p>
- <table class="gradient-table">
- <thead>
- <tr>
- <td>REPL Wrapper</td>
- <td>REST API</td>
- <td>Help</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>ask</code></td>
- <td><code>/ask/sync</code></td>
- <td><code>help --cmd=ask</code></td>
- </tr>
- <tr>
- <td><code>signin</code></td>
- <td><code>/signin</code></td>
- <td><code>help --cmd=signin</code></td>
- </tr>
- <tr>
- <td><code>signout</code></td>
- <td><code>/signout</code></td>
- <td><code>help --cmd=signout</code></td>
- </tr>
- <tr>
- <td><code>sugsyn</code></td>
- <td><code>/model/sugsyn</code></td>
- <td><code>help --cmd=sugsyn</code></td>
- </tr>
- <tbody>
- </table>
- <p>
- This is an example of the session where <code>call</code> command was used to issue REST <code>/signin</code>
- call and then REST <code>/signout</code> call:
- </p>
- <p>
- <img class="non-fluid-img" src="/images/cli4.png" alt="">
- </p>
- <p>
- The exactly the same sequence of calls can be performed quicker and easier using convenient
- <code>signing</code> and <code>signout</code> command wrappers:
- </p>
- <p>
- <img class="non-fluid-img" src="/images/cli5.png" alt="">
- </p>
- <p>
- Note that for <code>signout</code> command you don't even have to specify the access token
- as it is taken from the current server context automatically.
- </p>
+ We use <code>tail -n +2</code> to skip the 1st line of the output that contains HTTP return code.
</li>
<li>
- <b>REPL Commands:</b>
- <p>
- REPL commands are set of utilities that you can use while in REPL mode. Although all of these commands, as always,
- can be executed in the command like mode - they make most sense in REPL mode (except for <code>help</code> command).
- </p>
+ We use <a target=_blank href="https://stedolan.github.io/jq/">jq</a> utility to parse JSON inline to extract
+ <code>acsTok</code> field.
</li>
<li>
- <b>Miscellaneous Tools:</b>
- <p>
- Miscellaneous commands contain number of convenient utilities. For example, you can generate the
- project stub for Scala and SBT using the following command:
- </p>
- <p>
- <img class="non-fluid-img" src="/images/cli6.png" alt="">
- </p>
+ We use <code>tr -d '"'</code> to remove surrounding double quotes to get out final result.
</li>
- </ol>
+ </ul>
</section>
</div>
<div class="col-md-2 third-column">
@@ -278,7 +207,7 @@ id: script
<li><a href="#overview">Overview</a></li>
<li><a href="#quick_start">Quick Start</a></li>
<li><a href="#os_commands">OS Commands</a></li>
- <li><a href="#usage">Usage</a></li>
+ <li><a href="#tips">Tips <span class="amp">&</span> Tricks</a></li>
{% include quick-links.html %}
</ul>
</div>