Added tool environemnt use documentation (#4)

* Added tool environemnt use documentation

* Adding CI job to build the API docs

* Fixing yaml

.github/workflows/docs.yaml

@@ -0,0 +1,42 @@
+##
+## Copyright (c) 2023 The Johns Hopkins University Applied Physics
+## Laboratory LLC.
+##
+## This file is part of the Asynchronous Network Managment System (ANMS).
+##
+## 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.
+##
+## This work was performed for the Jet Propulsion Laboratory, California
+## Institute of Technology, sponsored by the United States Government under
+## the prime contract 80NM0018D0004 between the Caltech and NASA under
+## subcontract 1658085.
+##
+
+name: Build documentation
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y python3-pip
+          pip3 install --upgrade pip
+          pip3 install .[docs]
+      - name: build
+        run: ./build_docs.sh
+      - uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: docs/_build

docs/ace_ari.rst

@@ -6,3 +6,32 @@ The ARI Transcoder Tool
     :module: ace.tools.ace_ari
     :func: get_parser
     :prog: ace_ari
+
+Environment Variables
+---------------------
+
+The following environment variables control how the tool searches for and loads ADM files.
+
+ADM_PATH
+    This is the highest priority search path.
+    All files in the directory named by this variable following the pattern ``*.json`` are loaded as ADMs.
+
+XDG_DATA_HOME, XDG_DATA_DIRS
+    These directories are used in accordance with the `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_ with the suffix path ``/ace/adms``.
+    All files in the search subdirectories following the pattern ``*.json`` are loaded as ADMs.
+
+XDG_CACHE_HOME
+    This directory is used in accordance with the `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_ with the suffix path ``/ace`` for storing cached data.
+    The two cache names used are ``adms.sqlite`` file and ``ply`` directory.
+
+Examples
+````````
+
+The XDG-default local search paths for ADM files would be the priority ordering of
+
+#. ``$ADM_PATH``
+#. ``$HOME/.local/share/ace/adms``
+#. ``/usr/local/share/ace/adms``
+#. ``/usr/share/ace/adms``
+
+And the XDG-default cache directory for ADM lookup and ARI parsing is ``$HOME/.cache/ace``.

src/ace/tools/ace_ari.py

@@ -20,6 +20,13 @@
 # subcontract 1658085.
 #
 ''' This tool converts ARIs between different encoding forms.
+
+It uses environment variables to control where ADMs are searched for and
+command options to control the ARI conversion.
+For ``text`` or ``cborhex`` forms of input or output, each line is handled 
+as a separate ARI and converted independently until the input stream is ended.
+For ``cbor`` form of input or output, the stream is treated as a CBOR sequence
+and each item is handled as a separate ARI.
 '''
 import argparse
 import io
@@ -42,16 +49,16 @@ def get_parser() -> argparse.ArgumentParser:
                         help='The minimum log severity.')
     parser.add_argument('--inform', choices=('text', 'cbor', 'cborhex'),
                         default='text',
-                        help='The input encoding')
+                        help='The input encoding.')
     parser.add_argument('--input', default='-',
-                        help='The input file or "-" for stdin')
+                        help='The input file or "-" for stdin stream.')
     parser.add_argument('--outform', choices=('text', 'cbor', 'cborhex'),
                         default='cbor',
-                        help='The desired output encoding')
+                        help='The desired output encoding.')
     parser.add_argument('--output', default='-',
-                        help='The output file or "-" for stdout')
+                        help='The output file or "-" for stdout stream.')
     parser.add_argument('--must-nickname', action='store_true', default=False,
-                        help='Require that a nickname exist when converting from text')
+                        help='Require that a nickname exist when converting from text.')
     return parser