Wip guides

README.md

@@ -1,16 +1,18 @@
 # Introduction 
 
 ### Read the Docs
-* [Latest production docs](http://openaps.readthedocs.org/en/latest/index.html)
-* [Dev docs](http://openaps.readthedocs.org/en/dev/index.html)
-* [Dana's docs](http://openaps.readthedocs.org/en/dana-dev/index.html)
+* [Latest production docs](https://openaps.readthedocs.org/en/latest/index.html)
+* [Dev docs](https://openaps.readthedocs.org/en/dev/index.html)
+* [Dana's docs](https://openaps.readthedocs.org/en/dana-dev/index.html)
 
 ## Welcome
 
 Welcome to the [openaps](https://github.com/openaps/) documentation!
 
 openaps is part of a set of tools to support a self-driven Do-It-Yourself (DIY) implementation of an artificial pancreas based on the [OpenAPS reference design](http://openaps.org/open-artificial-pancreas-system-openaps-reference-design/). 
 
+Here are two visuals to show you what the physical hardware components of an OpenAPS setup look like - ![version A](./docs/docs/IMG_1112.jpg) is without labels; ![version B](docs/Images/piSetup.jpg) contains labels to describe the parts.
+
 By proceeding to use these tools or any piece within, you agree to the copyright (see LICENSE.txt for more information) and release any contributors from liability. 
 
 The tools may be categorized as: 1)  **monitor** collecting data and

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.
@@ -60,8 +61,8 @@
 
 # General information about the project.
 project = u'OpenAPS'
-copyright = u'2016, Ben West'
-author = u'Ben West'
+copyright = u'2016, Ben West, Dana Lewis, and openaps contributors'
+author = u'Ben West, Dana Lewis, Scott Leibrand, openaps community'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -123,18 +124,43 @@
 # a list of builtin themes.
 html_theme = 'alabaster'
 
+
+extra_nav_links = {
+  'docs': 'https://github.com/openaps/docs',
+  'openaps': 'https://github.com/openaps/openaps',
+  'dexcom_reader': 'https://github.com/openaps/dexcom_reader',
+  'decocare': 'https://github.com/bewest/decoding-carelink',
+  'openaps.org': 'https://openaps.org/',
+}
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
 # alabaster
+theme_github_user = 'openaps'
+theme_github_repo = 'docs'
 html_theme_options = {
   'show_related': True,
+  'github_user': theme_github_user,
+  'github_repo': theme_github_repo,
+  'logo': 'openaps-logo.png',
+  # TODO: ???? doesn't work?
+  'extra_nav_links': extra_nav_links,
+}
+
+"""
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+  'display_github': True,
+  'github_user': 'openaps',
+  'github_repo': 'docs',
 }
+import sphinx_rtd_theme
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path( )]
+"""
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-html_theme_path = [alabaster.get_path( )]
+html_theme_path = []
+# html_theme_path = [alabaster.get_path( )]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -146,6 +172,8 @@
 # The name of an image file (relative to this directory) to place at the top
 # 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
@@ -165,6 +193,7 @@
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -173,7 +202,10 @@
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 # for alabaster
-html_sidbars = {
+"""
+html_sidebars = { }
+"""
+html_sidebars = {
   '**': [
       'about.html',
       'navigation.html',
@@ -183,6 +215,7 @@
   ]
 }
 
+
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}
@@ -251,12 +284,13 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'OpenAPS.tex', u'OpenAPS Documentation',
-     u'Ben West', 'manual'),
+     author, 'manual'),
 ]
 
 # 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/introduction/communication-support-channels.md

@@ -1,6 +1,6 @@
 # Where to go for help with your implementation
 
-There are several ways to communicate with other participants and contributors in the #OpenAPS project. See also the [Resources](../Resources/) section for additional assistance.
+There are several ways to communicate with other participants and contributors in the #OpenAPS project. See also the [Resources](../Resources/index.rst) section for additional assistance.
 
 **Note:** It's best practice not to share your pump's serial number, so make sure not to include it in pictures or pasted text output when seeking help on pump communication.
 

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
+