From 8fa6b52ab98ba7d0be6b2d66e95f1a901b1e58f0 Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 11:35:07 -0700 Subject: [PATCH 01/10] Add time sync to Edison bootstrap docs Document a time sync before the first HTTPS fetch in the Edison bootstrap snippet, keep master as the default branch while allowing override, and retry the GitHub fetch after another time sync if the rig clock is wrong. --- docs/docs/Build Your Rig/edison-install.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/docs/Build Your Rig/edison-install.md b/docs/docs/Build Your Rig/edison-install.md index 6c3eeb703..775421721 100644 --- a/docs/docs/Build Your Rig/edison-install.md +++ b/docs/docs/Build Your Rig/edison-install.md @@ -19,6 +19,7 @@ The box below is the Bootstrap script, and it will complete steps 2 and 3 for yo ``` #!/bin/bash ( +BRANCH=master dmesg -D echo Scanning for wifi networks: ifup wlan0 @@ -47,13 +48,23 @@ echo -e "\nAttempting to bring up wlan0:\n" ifdown wlan0; ifup wlan0 sleep 10 echo -ne "\nWifi SSID: "; iwgetid -r +echo -e "\nSyncing time:\n" +ntpd -gq || ntpdate -u pool.ntp.org || true +sleep 2 +date sleep 5 -curl https://raw.githubusercontent.com/openaps/oref0/master/bin/openaps-install.sh > /tmp/openaps-install.sh -bash /tmp/openaps-install.sh +echo "Press Enter to continue installing the current release ($BRANCH) of oref0," +read -p "or enter the oref0 branch name to install." -r +BRANCH=${REPLY:-$BRANCH} +curl -L https://raw.githubusercontent.com/openaps/oref0/$BRANCH/bin/openaps-install.sh -o /tmp/openaps-install.sh || { + ntpd -gq || ntpdate -u pool.ntp.org || true + curl -L https://raw.githubusercontent.com/openaps/oref0/$BRANCH/bin/openaps-install.sh -o /tmp/openaps-install.sh +} +bash /tmp/openaps-install.sh $BRANCH ) ``` -Copy all of those lines; go back to Terminal/PuTTY and paste into the command line (Paste in PuTTY is just a right mouse click). Then, hit `enter`. The screenshot below is an example of what the pasted text will look like (highlighted in blue for clarity). *(If you have trouble copying from the box, [click here](https://raw.githubusercontent.com/openaps/oref0/dev/bin/openaps-bootstrap.sh) and ctrl-a or command-a to copy the text from there.)* +Copy all of those lines; go back to Terminal/PuTTY and paste into the command line (Paste in PuTTY is just a right mouse click). Then, hit `enter`. The screenshot below is an example of what the pasted text will look like (highlighted in blue for clarity). ************* Note: **This setup script will require you to have an available working internet connection to be successful.** If anything fails during the installation, the setup may end early before you get to the setup script questions. In that case, you can just paste the script above into the command line again and try again. (Don't try to use the up arrow, it probably won't work.) If you get repeated failures, bring your questions and error messages into Gitter or FB for help with troubleshooting. From 2f7bdd07940ac3755486f3459369047d9de0a17e Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 11:47:03 -0700 Subject: [PATCH 02/10] Add Read the Docs config --- .readthedocs.yaml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..f48c19707 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.8" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: requirements.txt From fb0248d1253f747f45c713903eac7fee44839f85 Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 11:49:21 -0700 Subject: [PATCH 03/10] Pin legacy docs build dependencies --- requirements.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/requirements.txt b/requirements.txt index 48ab9395a..9cb5a3f51 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,6 @@ recommonmark==0.4.0 sphinx==1.5.6 +Jinja2<3.1 +MarkupSafe<2.1 openaps docutils<0.18 From 9abfeb29843f4a7edd674a51485a89893ecf8cd8 Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 11:50:41 -0700 Subject: [PATCH 04/10] Pin alabaster for legacy docs build --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 9cb5a3f51..56a73b609 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ recommonmark==0.4.0 sphinx==1.5.6 +alabaster<0.7.13 Jinja2<3.1 MarkupSafe<2.1 openaps From d80530c6631178d82eea3d50058f64c0c14c53fc Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 11:53:38 -0700 Subject: [PATCH 05/10] Restore classic Read the Docs theme --- docs/conf.py | 19 ++++++------------- requirements.txt | 1 + 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a21419c34..8ee220db2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,6 +24,7 @@ from recommonmark.parser import CommonMarkParser from recommonmark.transform import AutoStructify import alabaster +import sphinx_rtd_theme # -- General configuration ------------------------------------------------ @@ -150,20 +151,13 @@ 'extra_nav_links': extra_nav_links, } -""" -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( )] -""" +# Match the classic Read the Docs rendering used on the published "latest" docs. +html_theme = '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 # " v documentation". @@ -433,4 +427,3 @@ def setup(app): 'enable_eval_rst': True, }, True) app.add_transform(AutoStructify) - diff --git a/requirements.txt b/requirements.txt index 56a73b609..8942ce029 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ recommonmark==0.4.0 sphinx==1.5.6 +sphinx_rtd_theme==0.2.4 alabaster<0.7.13 Jinja2<3.1 MarkupSafe<2.1 From 295c4d1410363b769117834e5834ec041c10175b Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 11:54:50 -0700 Subject: [PATCH 06/10] Drop incompatible RTD theme options --- docs/conf.py | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8ee220db2..e4cafb93e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -139,21 +139,10 @@ # 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, -} - # Match the classic Read the Docs rendering used on the published "latest" docs. html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] From b7a00ce4192b11f9f658f6f74ad9d009f1dbe26e Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 11:57:15 -0700 Subject: [PATCH 07/10] Restore green code block styling --- docs/_static/openaps-docs.css | 7 +++++++ docs/conf.py | 1 + 2 files changed, 8 insertions(+) create mode 100644 docs/_static/openaps-docs.css diff --git a/docs/_static/openaps-docs.css b/docs/_static/openaps-docs.css new file mode 100644 index 000000000..3b69e52c7 --- /dev/null +++ b/docs/_static/openaps-docs.css @@ -0,0 +1,7 @@ +.rst-content pre, +.rst-content div[class^="highlight"] pre, +.rst-content .highlight pre, +.rst-content code.literal, +code.docutils.literal { + background: #e6f4ea; +} diff --git a/docs/conf.py b/docs/conf.py index e4cafb93e..8de8f3225 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -408,6 +408,7 @@ rtd_version = os.environ.get('READTHEDOCS_VERSION') hosted_root = 'https://openaps.readthedocs.org/en/%s/' % rtd_version def setup(app): + app.add_stylesheet('openaps-docs.css') app.add_config_value('recommonmark_config', { # 'url_resolver': lambda url: github_doc_root + url, 'url_resolver': lambda url: hosted_root + url + '.html', From 8c3a2155be8561c2caae1d04a94a12c5fdb7dc24 Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 11:58:54 -0700 Subject: [PATCH 08/10] Restore docs version label and nav colors --- docs/_static/openaps-docs.css | 5 +++++ docs/conf.py | 3 +++ 2 files changed, 8 insertions(+) diff --git a/docs/_static/openaps-docs.css b/docs/_static/openaps-docs.css index 3b69e52c7..7450a8357 100644 --- a/docs/_static/openaps-docs.css +++ b/docs/_static/openaps-docs.css @@ -5,3 +5,8 @@ code.docutils.literal { background: #e6f4ea; } + +.wy-side-nav-search, +.wy-nav-top { + background: #2980b9; +} diff --git a/docs/conf.py b/docs/conf.py index 8de8f3225..e9eabffdd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -407,6 +407,9 @@ if on_rtd: rtd_version = os.environ.get('READTHEDOCS_VERSION') hosted_root = 'https://openaps.readthedocs.org/en/%s/' % rtd_version + if rtd_version: + version = rtd_version + release = rtd_version def setup(app): app.add_stylesheet('openaps-docs.css') app.add_config_value('recommonmark_config', { From 79250b6cafc65b894b840feea74fb66c13688caf Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 12:41:29 -0700 Subject: [PATCH 09/10] Tighten Edison time sync bootstrap step --- docs/docs/Build Your Rig/edison-install.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/docs/Build Your Rig/edison-install.md b/docs/docs/Build Your Rig/edison-install.md index 775421721..9725a93b1 100644 --- a/docs/docs/Build Your Rig/edison-install.md +++ b/docs/docs/Build Your Rig/edison-install.md @@ -49,15 +49,14 @@ ifdown wlan0; ifup wlan0 sleep 10 echo -ne "\nWifi SSID: "; iwgetid -r echo -e "\nSyncing time:\n" -ntpd -gq || ntpdate -u pool.ntp.org || true +service ntp stop || true; ntpd -gq; service ntp start || true; date sleep 2 -date sleep 5 echo "Press Enter to continue installing the current release ($BRANCH) of oref0," read -p "or enter the oref0 branch name to install." -r BRANCH=${REPLY:-$BRANCH} curl -L https://raw.githubusercontent.com/openaps/oref0/$BRANCH/bin/openaps-install.sh -o /tmp/openaps-install.sh || { - ntpd -gq || ntpdate -u pool.ntp.org || true + service ntp stop || true; ntpd -gq; service ntp start || true; date curl -L https://raw.githubusercontent.com/openaps/oref0/$BRANCH/bin/openaps-install.sh -o /tmp/openaps-install.sh } bash /tmp/openaps-install.sh $BRANCH From f8870256ea28bcb15d09dbb65bf1e730d19bb7b7 Mon Sep 17 00:00:00 2001 From: Scott Leibrand Date: Mon, 9 Mar 2026 12:42:29 -0700 Subject: [PATCH 10/10] Remove extra delay from Edison bootstrap docs --- docs/docs/Build Your Rig/edison-install.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/docs/Build Your Rig/edison-install.md b/docs/docs/Build Your Rig/edison-install.md index 9725a93b1..d854fab0d 100644 --- a/docs/docs/Build Your Rig/edison-install.md +++ b/docs/docs/Build Your Rig/edison-install.md @@ -50,8 +50,6 @@ sleep 10 echo -ne "\nWifi SSID: "; iwgetid -r echo -e "\nSyncing time:\n" service ntp stop || true; ntpd -gq; service ntp start || true; date -sleep 2 -sleep 5 echo "Press Enter to continue installing the current release ($BRANCH) of oref0," read -p "or enter the oref0 branch name to install." -r BRANCH=${REPLY:-$BRANCH}