docs: Use sphinx-js (#248)

Author: abmusse

.readthedocs.yml

@@ -0,0 +1,16 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt

docs/CommandCall.rst

@@ -0,0 +1,22 @@
+.. _CommandCall:
+
+Calling a Command
+-----------------
+
+CommandCall API
+^^^^^^^^^^^^^^^
+.. autoclass:: CommandCall
+   :members:
+
+.. autofunction:: clOptions
+.. autofunction:: shOptions
+.. autofunction:: commandCallConfig
+
+Example
+^^^^^^^^
+
+Call the RTVJOBA CL command
+""""""""""""""""""""""""""""
+
+.. literalinclude:: examples/rtvjoba.js
+   :language: javascript

docs/Connection.rst

@@ -0,0 +1,135 @@
+.. _Connection:
+
+Creating a Connection
+=====================
+
+Transports
+----------
+
+The ``Connection`` Class uses ``ODBC``, ``SSH``, ``idb``, and ``REST`` transports to access ``XMLSERVICE``.
+Some transports require prerequisite setup. Learn morre about each transport below.
+
+ODBC
+^^^^
+.. _guide: https://github.com/IBM/ibmi-oss-examples/blob/master/odbc/odbc.md#table-of-contents
+
+The ODBC transport establishes a database connection and calls XMLSERVICE stored procedure.
+Refer to the odbc guide_ for setup instructions.
+
+SSH
+^^^
+The SSH transport executes ``xmlservice-cli`` program via ssh.
+Install ``xmlservice-cli`` before using the ``SSH`` transport.
+
+.. code-block:: bash
+
+   $ yum install itoolkit-utils
+
+idb
+^^^^
+
+The idb transport establishes a database connection and calls the XMLSERVICE stored procedure.
+
+**NOTE** the idb transport is only supported on an IBM i system.
+
+REST
+^^^^
+The REST transport makes an HTTP request to an endpoint that process the XML input and returns XML output.
+
+Initial configuration is required for the endpoint.
+
+A quick example is to add the following to ``/www/apachedft/conf/httpd.conf``.
+
+
+.. code-block:: apache
+
+   ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/
+   <Directory /QSYS.LIB/XMLSERVICE.LIB/>
+   AllowOverride None
+   Require all granted
+   SetHandler cgi-script
+   Options +ExecCGI
+   </Directory>
+
+Connection API
+--------------
+
+.. autoclass:: Connection
+   :members:
+
+.. autofunction:: connectionConfig
+.. autofunction:: odbcOptions
+.. autofunction:: sshOptions
+.. autofunction:: idbOptions
+.. autofunction:: restOptions
+.. autofunction:: runCallback
+
+Examples
+--------
+
+Creating a ``Connection`` using the ``ODBC`` tranport.
+
+.. code-block:: js
+
+   const connection = new Connection({
+     transport: 'odbc',
+     transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword'}
+   });
+
+Creating a ``Connection`` using the ``ODBC`` tranport with a ``DSN``.
+
+.. code-block:: js
+
+   const connection = new Connection({
+     transport: 'odbc',
+     transportOptions: { dsn: '*LOCAL'}
+   });
+
+Creating a ``Connection`` with ``ssh`` tranport using private key to authenticate.
+
+.. code-block:: js
+
+   const connection = new Connection({
+     transport: 'ssh',
+     transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
+   });
+
+Creating a ``Connection`` using the ``ssh`` tranport with a private key to authenticate.
+
+.. code-block:: js
+
+   const { readFileSync } = require('fs');
+
+   const privateKey = readFileSync('path/to/privateKey', 'utf-8');
+
+   // NOTE if your privateKey also requires a passphrase provide it
+
+   const connection = new Connection({
+   transport: 'ssh',
+   transportOptions: { host: 'myhost', username: 'myuser', privateKey, passphrase: 'myphrase' }
+   });
+
+Creating a ``Connection`` using the ``idb`` tranport.
+
+.. code-block:: js
+
+   const connection = new Connection({
+     transport: 'idb',
+     transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypass' }
+   });
+
+Creating a ``Connection`` using the ``REST`` tranport.
+
+.. code-block:: js
+
+   const connection = new Connection({
+     transport: 'rest',
+     transportOptions: {
+        host: 'myhost',
+        database: '*LOCAL',
+        username: 'myuser',
+        password: 'mypass'
+        port: 80,
+        path:'/cgi-bin/xmlcgi.pgm',
+      }
+   });

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/ProgramCall.rst

@@ -0,0 +1,23 @@
+.. _ProgramCall:
+
+Calling a Program or Service Program
+------------------------------------
+
+ProgramCall API
+^^^^^^^^^^^^^^^
+.. autoclass:: ProgramCall
+   :members:
+
+.. autofunction:: programCallConfig
+.. autofunction:: parameterConfig
+.. autofunction:: returnConfig
+.. autofunction:: data
+
+Example
+^^^^^^^^
+
+Call the QUSROBJD Program
+"""""""""""""""""""""""""
+
+.. literalinclude:: examples/qusrobjd.js
+   :language: javascript

docs/conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+import json
+
+js_source_path = '../lib'
+primary_domain = 'js'
+
+# -- Project information -----------------------------------------------------
+
+project = 'nodejs-itoolkit'
+copyright = '2020, IBM'
+author = 'IBM'
+
+# The full version, including alpha/beta/rc tags
+# read the version from package.json
+with open('../package.json', 'r') as read_file:
+    package = json.load(read_file)
+    release = package['version']
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [ 
+  'sphinx_js',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The master toctree document.
+master_doc = 'index'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/deprecated.rst

@@ -0,0 +1,21 @@
+.. _deprecated:
+
+
+Deprecated Classes and Functions
+================================
+
+.. toctree::
+   :maxdepth: 1
+   
+   deprecated/iConn
+   deprecated/iCmd
+   deprecated/iDataQueue
+   deprecated/iNetwork
+   deprecated/iObj
+   deprecated/iPgm
+   deprecated/iProd
+   deprecated/iQsh
+   deprecated/iSh
+   deprecated/iSql
+   deprecated/iUserSpace
+   deprecated/iWork

docs/deprecated/examples/addQuery.js

@@ -0,0 +1,27 @@
+const { Connection, iSql } = require('itoolkit');
+const { parseString } = require('xml2js');
+
+const connection = new Connection({
+  transport: 'ssh',
+  transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' },
+});
+
+const sql = new iSql();
+
+sql.addQuery('SELECT LSTNAM, STATE FROM QIWS.QCUSTCDT');
+sql.fetch();
+sql.free();
+
+connection.add(sql);
+
+connection.run((error, xmlOutput) => {
+  if (error) {
+    throw error;
+  }
+  parseString(xmlOutput, (parseError, result) => {
+    if (parseError) {
+      throw parseError;
+    }
+    console.log(JSON.stringify(result));
+  });
+});

docs/deprecated/examples/addToLibraryList.js

@@ -0,0 +1,15 @@
+const { Connection, iObj } = require('itoolkit');
+
+const connection = new Connection({
+  transport: 'ssh',
+  transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' },
+});
+
+const obj = new iObj(connection);
+
+obj.addToLibraryList('QHTTPSVR', (error, output) => {
+  if (error) {
+    throw error;
+  }
+  console.log(output);
+});

docs/deprecated/examples/callProcedure.js

@@ -0,0 +1,28 @@
+const { Connection, iSql } = require('itoolkit');
+const { parseString } = require('xml2js');
+
+const connection = new Connection({
+  transport: 'ssh',
+  transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' },
+});
+
+const sql = new iSql();
+
+sql.prepare('call qsys2.tcpip_info()');
+sql.execute();
+sql.fetch();
+sql.free();
+
+connection.add(sql);
+
+connection.run((error, xmlOutput) => {
+  if (error) {
+    throw error;
+  }
+  parseString(xmlOutput, (parseError, result) => {
+    if (parseError) {
+      throw parseError;
+    }
+    console.log(JSON.stringify(result));
+  });
+});