Update installation docs 1.4.1 (#1810)

* [wip] Updated installation docs

* Add tabs for different OS installations

* Move installation methods to tabs

* Use tabs.css

* FIx styling error (line under last tab in terminal hint)

* Add installation instructions before TOC

* Replace mamba with conda

* Lint

* Find good light colors
not switching when change dark/light themes

* Get color scheme switching
with dark/light toggle button

* Upgrade website build dependencies

* Remove seemingly unneeded dependencies from workflow

* Add myst-nb>=0.16.0 lower bound

* Trigger dev website build

* Fix minor typo in css

* Add miniforge and one-liner installs for package managers

---------

Co-authored-by: roomrys <lmaree@ucsd.edu>
Co-authored-by: Talmo Pereira <talmo@salk.edu>

.conda/README.md

@@ -3,7 +3,7 @@ This folder defines the conda package build for Linux and Windows. There are run
 To build, first go to the base repo directory and install the build environment:
 
 ```
-mamba env create -f environment_build.yml -n sleap_build && conda activate sleap_build
+conda env create -f environment_build.yml -n sleap_build && conda activate sleap_build
 ```
 
 And finally, run the build command pointing to this directory:
@@ -15,7 +15,7 @@ conda build .conda --output-folder build -c conda-forge -c nvidia -c https://con
 To install the local package:
 
 ```
-mamba create -n sleap_0 -c conda-forge -c nvidia -c ./build -c https://conda.anaconda.org/sleap/ -c anaconda sleap=x.x.x
+conda create -n sleap_0 -c conda-forge -c nvidia -c ./build -c https://conda.anaconda.org/sleap/ -c anaconda sleap=x.x.x
 ```
 
 replacing x.x.x with the version of SLEAP that you just built.

.github/workflows/website.yml

@@ -8,7 +8,7 @@ on:
       # 'main' triggers updates to 'sleap.ai', all others to 'sleap.ai/develop'
       - main
       - develop
-      - fakebranch
+      - liezl/update-intallation-docs-1.4.1 # again!
     paths:
       - "docs/**"
       - "README.rst"
@@ -36,12 +36,8 @@ jobs:
           conda info
 
       - name: Build
-        # """Could not import extension myst_nb (exception: lxml.html.clean module is now 
-        # a separate project lxml_html_clean. Install lxml[html_clean] or 
-        # lxml_html_clean directly.)"""
         shell: bash -l {0}
         run: |
-          pip install lxml[html_clean]
           cd docs
           python make_api_doctree.py
           make html
@@ -62,4 +58,4 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_branch: gh-pages
           publish_dir: docs/build/html
-          destination_dir: develop
+          destination_dir: develop

dev_requirements.txt

@@ -5,13 +5,14 @@ pytest-qt>=4.0.0
 pytest-cov<=3.0.0
 pytest-xvfb
 ipython
-sphinx
+sphinx>=5.0  # sphinxcontrib.applehelp extension needs at least Sphinx v5.0
 # furo
 sphinx-book-theme
 sphinx-copybutton
+sphinx-tabs
 nbformat==5.1.3
-myst-nb==0.13.2
-myst-parser==0.15.2
+myst-nb>=0.16.0  # sphinx>=5.0 needs myst-nb>=0.16.0 
+myst-parser
 linkify-it-py
 sphinx-autobuild
 black==21.6b0

docs/_static/css/tabs.css

@@ -0,0 +1,91 @@
+.sphinx-tabs {
+  margin-bottom: 1rem;
+}
+
+[role="tablist"] {
+  border-bottom: 1px solid #a0b3bf;
+}
+
+.sphinx-tabs-tab {
+  position: relative;
+  font-family: Lato,'Helvetica Neue',Arial,Helvetica,sans-serif;
+  color: var(--pst-color-link);
+  line-height: 24px;
+  margin: 3px;
+  font-size: 16px;
+  font-weight: 400;
+  background-color: rgb(241 244 249);
+  border-radius: 5px 5px 0 0;
+  border: 0;
+  padding: 1rem 1.5rem;
+  margin-bottom: 0;
+}
+
+.sphinx-tabs-tab[aria-selected="true"] {
+  font-weight: 700;
+  border: 1px solid #a0b3bf;
+  border-bottom: 1px solid rgb(241 244 249);
+  margin: -1px;
+  background-color: rgb(242 247 255);
+}
+
+.admonition .sphinx-tabs-tab[aria-selected="true"]:last-child {
+  margin-bottom: -1px;
+}
+
+.sphinx-tabs-tab:focus {
+  z-index: 1;
+  outline-offset: 1px;
+}
+
+.sphinx-tabs-panel {
+  position: relative;
+  padding: 1rem;
+  border: 1px solid #a0b3bf;
+  margin: 0px -1px -1px -1px;
+  border-radius: 0 0 5px 5px;
+  border-top: 0;
+  background: rgb(242 247 255);
+}
+
+.sphinx-tabs-panel.code-tab {
+  padding: 0.4rem;
+}
+
+.sphinx-tab img {
+    margin-bottom: 24px;
+}
+
+/* Dark theme preference styling */
+
+html[data-theme="dark"] .sphinx-tabs-panel {
+  color: white;
+  background-color: rgb(50, 50, 50);
+}
+
+html[data-theme="dark"] .sphinx-tabs-tab {
+  color: var(--pst-color-link);
+  background-color: rgba(255, 255, 255, 0.05);
+}
+
+html[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] {
+  border-bottom: 2px solid rgb(50, 50, 50);
+  background-color: rgb(50, 50, 50);
+}
+
+/* Light theme preference styling */
+
+html[data-theme="light"] .sphinx-tabs-panel {
+  color: black;
+  background-color: white;
+}
+
+html[data-theme="light"] .sphinx-tabs-tab {
+  color: var(--pst-color-link);
+  background-color: rgba(0, 0, 0, 0.05);
+}
+
+html[data-theme="light"] .sphinx-tabs-tab[aria-selected="true"] {
+  border-bottom: 2px solid white;
+  background-color: white;
+}

docs/conf.py

@@ -59,6 +59,7 @@
     "sphinx.ext.linkcode",
     "sphinx.ext.napoleon",
     "sphinx_copybutton",
+    "sphinx_tabs.tabs",  # For tabs inside docs
     # https://myst-nb.readthedocs.io/en/latest/
     "myst_nb",
 ]
@@ -174,6 +175,12 @@ def linkcode_resolve(domain, info):
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'css/tabs.css',
+]
+
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -220,3 +227,7 @@ def linkcode_resolve(domain, info):
 
 # https://myst-nb.readthedocs.io/en/latest/use/config-reference.html
 jupyter_execute_notebooks = "off"
+
+# Sphinx-tabs settings
+# https://sphinx-tabs.readthedocs.io/en/latest/
+sphinx_tabs_disable_css_loading = True  # Use the theme's CSS