General reorganization and cleanup - hardware, install steps, flashing, background reading

.gitignore

@@ -15,3 +15,7 @@ _book
 *.mobi
 *.pdf
 .*.sw[op]
+
+# All build output (HTML etc.)
+build
+denv

docs/conf.py

@@ -41,8 +41,13 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     # 'alabaster',
+    'sphinx.ext.autosectionlabel', # Auto-generate section labels.
 ]
 
+# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
+# rather than 'path/to/file:heading'
+autosectionlabel_prefix_document = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -125,7 +130,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#html_theme = 'default`
+html_theme = 'sphinx_rtd_theme'
 
 
 extra_nav_links = {
@@ -138,31 +143,17 @@
 # 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.
-# 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,
+    'collapse_navigation': False,
+    'sticky_navigation': False,
+    'navigation_depth': 3,
+    'titles_only': False
 }
 
-"""
-html_theme = 'default'
-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 = []
 # html_theme_path = [alabaster.get_path( )]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
@@ -419,11 +410,12 @@
 #epub_use_index = True
 
 github_doc_root = 'https://github.com/openaps/docs/tree/master/'
-hosted_root = 'http://localhost:8000/'
+hosted_root = os.environ.get('HOSTEDROOT', 'http://localhost:8000/') # Allow setting custom root in local .env file for serving static files
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 if on_rtd:
   rtd_version = os.environ.get('READTHEDOCS_VERSION')
-  hosted_root = 'https://openaps.readthedocs.org/en/%s/' % rtd_version
+  rtd_domain = os.environ.get('READTHEDOCS_PROJECT')
+  hosted_root = 'https://%s.readthedocs.org/en/%s/' % (rtd_domain, rtd_version)
 def setup(app):
     app.add_config_value('recommonmark_config', {
             # 'url_resolver': lambda url: github_doc_root + url,
@@ -432,5 +424,4 @@ def setup(app):
             'enable_auto_doc_ref': True,
             'enable_eval_rst': True,
             }, True)
-    app.add_transform(AutoStructify)
-
+    app.add_transform(AutoStructify)

docs/docs/Build Your Rig/install-overview.md

@@ -0,0 +1,21 @@
+# Installing OpenAPS on your rig
+
+Getting OpenAPS running on your rig generally takes five steps:
+
+1. **Jubilinux installation** (called "flashing" the Edison - Pi users can skip to step 2). This may already be done for you if you purchased a pre-flashed Edison board.  
+2. **Getting first wifi network connection and installing "dependencies"** (helper code that make all the OpenAPS code function). This is done using what is called the "bootstrap" script.
+3. **Installing your OpenAPS loop**. This is done using what is called the "setup" script.
+4. **Watching the Pump-loop Log**. This is an important, required step. You need to be familiar with how to read and access your logs.
+5. **Finish your setup**: all the polishing steps to your OpenAPS setup.  Things like optimizing your settings, preferences, BT-tethering, IFTTT, etc.
+
+Going through steps 1-2 may take about 1-3 hours depending on your internet connection, whether the edison was pre-flashed, and comfort level with the instructions.  At the end of the bootstrap script (step 2), you will be asked if you want to continue on with the set-up script (step 3).  If you need to take a break and come back to step 3 later, you can answer "no" to continuing on and come back later.
+
+Before you start, it's a good idea to have some basic familiarity with using the command line on your computer, via a program like Terminal (on Mac) or Command Line (on Windows). This will be helpful not just for initial installation, but for monitoring and adjusting your setup later. [Here's a good introduction to using Terminal on Mac.](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) You can also reference the [generally-useful Linux commands](<../Troubleshooting/General_linux_troubleshooting>) from the troubleshooting guide.
+
+Some conventions used in these docs:
+
+* Wherever you see text that is formatted `like this`, it is a code snippet. You should copy and paste those code snippets instead of attempting to type these out; this will save you debugging time for finding your typos.
+* Double check that your copy-paste has copied correctly.  Sometimes a paste may drop a character or two and that will cause an error in the command that you are trying to execute.  Sometimes, depending on what step you are doing, you may not see the issue.  So, do make a point of double checking the paste before pressing return.
+* You will see a <tt>$</tt> at the beginning of many of the lines of code. This
+  indicates that it is to be entered and executed at the terminal prompt. Do not type in the dollar sign <tt>$</tt>.
+* Wherever there are `<bracketed_components>` in the code, these are meant for you to insert your own information. Most of the time, it doesn't matter what you choose **as long as you stay consistent throughout this guide**. That means if you choose `myedison` as your  `<edisonhostname>`, you must use `myedison` every time you see `<edisonhostname>`. Do not include the `< >` brackets in your commands when you enter them.  So for the example above, if the code snipped says `ssh root@<edisonhostname>.local`, you would enter `ssh [email protected]`