Wip guides

docs/conf.py

@@ -34,9 +34,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.ifconfig',
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
-    'alabaster',
+    # 'alabaster',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -159,7 +160,7 @@
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = []
-html_theme_path = [alabaster.get_path( ),]
+# html_theme_path = [alabaster.get_path( )]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -172,6 +173,7 @@
 # of the sidebar.
 #html_logo = None
 html_logo = '_static/openaps-logo.png'
+html_logo = None
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -201,7 +203,9 @@
 #html_sidebars = {}
 # for alabaster
 """
-html_sidbars = {
+html_sidebars = { }
+"""
+html_sidebars = {
   '**': [
       'about.html',
       'navigation.html',
@@ -210,9 +214,7 @@
       'donate.html',
   ]
 }
-"""
 
-html_sidbars = { }
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -288,6 +290,7 @@
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
+latex_logo = '_static/openaps-logo.png'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.

docs/docs/openaps-guide/core/alias.md

@@ -0,0 +1,78 @@
+
+# Alias - shortcut for any command
+
+An **alias** allows us to assign a nickname to any command or group of
+commands.  It's very similar to [git alias], let's take a look at the `openaps
+alias --help` output:
+
+
+
+```
+usage: openaps-alias [-h] {add,remove,show} ...
+
+ openaps-alias - manage aliases
+
+optional arguments:
+  -h, --help         show this help message and exit
+
+## Alias Menu:
+   aliases - manage alias configurations 
+
+  {add,remove,show}  Operation
+    add              add - add an alias
+    remove           remove - remove an alias
+    show             show - show all aliases
+```
+
+
+Let's try a very trivial example with hello world again, `echo hello world` as an alias:
+
+Adding an alias takes a name, and an alias definition (the commands to run).
+The commands to run may be any command inside `openaps` toolkit, or if it
+starts with a bang (`!`), it can run any arbitrary tool available on the
+system.
+
+## Hello world example
+```
+$ openaps alias add echo "! bash -c \"echo hello \$1\" --"
+added echo ! bash -c "echo hello $1" --
+$ openaps echo HUMAN
+hello HUMAN
+```
+## Openaps example
+We can "rename" commands this way, for example we can alias `openaps invoke` to `openaps report invoke`:
+
+```
+$ openaps alias add invoke "report invoke"
+added invoke report invoke
+$ openaps invoke fake-cgm-data.txt fake-oref0-data.txt
+fake-cgm://JSON/shell/fake-cgm-data.txt
+reporting fake-cgm-data.txt
+fake-oref0://JSON/shell/fake-oref0-data.txt
+reporting fake-oref0-data.txt
+```
+
+## Grouping commands logically
+We can also group large groups of command invocations into one simple alias:
+```bash
+$ openaps alias add gather-all-fake \
+  "report invoke howdy.txt fake-pump-data.txt fake-cgm-data.txt fake-oref0-data.txt"
+added gather-all-fake report invoke howdy.txt fake-pump-data.txt fake-cgm-data.txt fake-oref0-data.txt
+```
+```bash
+$ openaps gather-all-fake
+howdy://text/shell/howdy.txt
+reporting howdy.txt
+fake-pump://JSON/shell/fake-pump-data.txt
+reporting fake-pump-data.txt
+fake-cgm://JSON/shell/fake-cgm-data.txt
+reporting fake-cgm-data.txt
+fake-oref0://JSON/shell/fake-oref0-data.txt
+reporting fake-oref0-data.txt
+```
+
+An alias runs all the commands associated with it's definition.
+It's the same as running the commands themselves.
+
+[git alias]: https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases
+

docs/docs/openaps-guide/core/devices.md

@@ -0,0 +1,200 @@
+
+# Devices - aka **using** openaps
+
+There are several **vendors** that built into the core of openaps.
+There are two tools we can use to examine which **vendors** are available for
+**use** by a **device**.
+
+## What can we use?
+
+The `openaps use` command allows us to interact with devices.  Let's ask it for help:
+
+    openaps use -h
+
+```bash
+usage: openaps-use [-h] [--format {text,json,base,stdout}] [--output OUTPUT]
+                   [--version]
+                   device ...
+[... edited for brevity ...]
+Known Devices Menu:
+  These are the devices openaps knows about:    
+
+  device                Name and description:
+
+Once a device is registered in openaps.ini, it can be used.
+```
+
+Notice the `Known Devices Menu:` is empty, this means `openaps` doesn't know
+about anything yet.
+Let's try the `openaps device` command instead:
+
+```
+usage: openaps-device [-h] {add,remove,show} ...
+
+  openaps-device - Manage device configurations.
+
+positional arguments:
+  {add,remove,show}  Operation
+    add              add - add a new device configuration
+    remove           remove - remove a device configuration
+    show             show - show all devices
+
+optional arguments:
+  -h, --help         show this help message and exit
+
+show    - lists all known devices
+add     - add a new device
+remove  - remove a device
+```
+
+Lots of options there: the `devices` command allows us to teach openaps about our devices.
+The **use** command above had an empty devices menu what does `device show` say?
+```
+```
+Nothing yet!  Both `openaps use` and `openaps device show` indicate nothing for us
+to interact with yet.  Let's look at the `--help` output for `device add`:
+
+```
+usage: openaps-device add [-h] [--extra EXTRA]
+                          name {dexcom,medtronic,process,units} ...
+
+add    - add a new device configuration
+
+positional arguments:
+  name
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --extra EXTRA, -e EXTRA
+                        Name of extra ini file to use.
+
+## VendorConfigurations:
+  {dexcom,medtronic,process,units}
+                        Operation
+    dexcom              Dexcom - openaps driver for dexcom
+    medtronic           Medtronic - openaps driver for Medtronic
+    process             process - a fake vendor to run arbitrary commands
+    units               Units - units tool for openaps
+```
+
+Notice `VendorConfigurations`.  These are the default **vendors** that ship
+with `openaps`.  However, `openaps` doesn't know we want to **use**
+them yet.  `openaps device add` allows us to name our device.  The
+name we *add* to openaps will be the name we **use** later.
+
+## **Devices** configure **use**
+
+### A trivial device
+
+Let's use `echo` to create a trivial device that just says "hello
+world."
+`echo` is a unix **process**, the **VendorConfigurations** above include a
+`process` vendor we can use to illustrate the relationship between **uses**
+and **devices**.
+Let's warm up with some examples:
+
+```bash
+echo 'hello world!'
+```
+That should print hello world on the screen.  We can run this over and
+over again just for fun, but let's discover how to teach `openaps` how
+to do this.
+
+```bash
+openaps device add howdy process  echo 'hello world!'
+added process://howdy/echo/hello world!
+```
+
+What did this do? Let's check `git show`:
+
+```diff
+commit 8e198ad8556ea6df4d4f6459d212eee316b89a0e
+Author: Ben West <bewest@gmail.com>
+Date:   Sun Mar 27 15:45:16 2016 -0700
+
+    openaps-device add howdy process echo hello world!
+
+          TODO: better change descriptions
+          /usr/local/bin/openaps-device add howdy process echo hello world!
+
+diff --git a/openaps.ini b/openaps.ini
+index e69de29..d4a23d0 100644
+--- a/openaps.ini
++++ b/openaps.ini
+@@ -0,0 +1,4 @@
++[device "howdy"]
++vendor = openaps.vendors.process
++extra = howdy.ini
++
+```
+
+The `openaps * add` commands all change some of the INI configurations.
+
+Did the **use** menu change at all? `openap use -h`
+
+```
+[...]
+Known Devices Menu:
+  These are the devices openaps knows about:    
+
+  device                Name and description:
+    howdy               process - a fake vendor to run arbitrary commands
+
+```
+
+Now there's a **howdy** device in the **use** menu.  The **use** menu adapts
+to our custom devices.  Now we can **use** the device interactively: `openaps
+use howdy -h`, remember, we can always add `-h` to get more help/hints.
+Take note of that `--format text` option... our trivial `howdy` tool just
+prints a line of text.  Most tools actually use a format called json (and it's
+the default), but for this example, we'll stick with `--format text`.
+
+```
+usage: openaps-use howdy [-h] USAGE ...
+
+optional arguments:
+  -h, --help  show this help message and exit
+
+## Device howdy:
+  vendor openaps.vendors.process
+
+  process - a fake vendor to run arbitrary commands
+
+
+
+  USAGE       Usage Details
+    shell     run a process in a subshell
+```
+
+Hmm, because this a *unix process*, the **use** for this one is called
+**shell**.  What happens if we just add that word to the end? `openaps use
+--format text howdy shell`
+
+```
+$ openaps use --format text howdy shell
+hello world!
+```
+
+Now it prints `hello world!` because we are interactively **using** the
+**device**.  The **device** was configured through the `add` command, and
+saved in the INI as the `process` **vendor**.  The `process` **vendor** only
+exposes a single **use**: the `shell` use allows us to run any unix process.
+The **device** commands configure the **uses**.  The **use** menu adapts to
+the registered **devices**.  We can interact with a device by using it.
+
+
+## Summary
+
+Hopefully this illustrates the relationship between the openaps **device** and
+**use** tools.  The `device` command allows bringing devices into your
+instance, and **use** allows interacting with them.  Let's take a deeper look
+at this relationship looking at the other vendors that might share a closer
+relationship to diabetes.
+
+  * [medtronic builtin]
+
+
+[medtronic builtin]: medtronic.md
+[dexcom builtin]: dexcom.md
+[overview]: ../overview.md
+