From 3556f7f6eadbb0c058a88ff363af289082dc6f69 Mon Sep 17 00:00:00 2001 From: roomrys <38435167+roomrys@users.noreply.github.com> Date: Thu, 13 Jun 2024 14:02:33 -0700 Subject: [PATCH 01/16] [wip] Updated installation docs --- docs/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index dcb233904..2a8ed70b9 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,8 +1,8 @@ # Installation -SLEAP can be installed as a Python package on Windows, Linux, Mac OS X, and Mac OS Apple Silicon. +SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. -SLEAP requires many complex dependencies, so we **strongly** recommend using [Mambaforge](https://mamba.readthedocs.io/en/latest/installation.html) to install it in its own isolated environment. See {ref}`Installing Mambaforge` below for more instructions. +SLEAP requires many complex dependencies, so we **strongly** recommend using a package manager such as [Miniconda](https://docs.anaconda.com/free/miniconda/) to install SLEAP in its own isolated environment. See the [Miniconda website](https://docs.anaconda.com/free/miniconda/) for installation instructions. The Anaconda or Mamba package managers will also work well. However, take care not to install multiple different conda-based package managers - choose one and stick with it. The newest version of SLEAP can always be found in the [Releases page](https://github.com/talmolab/sleap/releases). From d58879b4ae7938f0f61bc847d6925d74a98b8384 Mon Sep 17 00:00:00 2001 From: roomrys <38435167+roomrys@users.noreply.github.com> Date: Fri, 14 Jun 2024 17:21:00 -0700 Subject: [PATCH 02/16] Add tabs for different OS installations --- .github/workflows/website.yml | 3 +- docs/conf.py | 1 + docs/installation.md | 201 ++++++++++++++-------------------- 3 files changed, 83 insertions(+), 122 deletions(-) diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 544a462b5..453f331a0 100644 --- a/.github/workflows/website.yml +++ b/.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 paths: - "docs/**" - "README.rst" @@ -42,6 +42,7 @@ jobs: shell: bash -l {0} run: | pip install lxml[html_clean] + pip install sphinx-tabs cd docs python make_api_doctree.py make html diff --git a/docs/conf.py b/docs/conf.py index d8470a190..9bdfdcfb6 100644 --- a/docs/conf.py +++ b/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", ] diff --git a/docs/installation.md b/docs/installation.md index 2a8ed70b9..462fb0010 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,7 +2,7 @@ SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. -SLEAP requires many complex dependencies, so we **strongly** recommend using a package manager such as [Miniconda](https://docs.anaconda.com/free/miniconda/) to install SLEAP in its own isolated environment. See the [Miniconda website](https://docs.anaconda.com/free/miniconda/) for installation instructions. The Anaconda or Mamba package managers will also work well. However, take care not to install multiple different conda-based package managers - choose one and stick with it. +SLEAP requires many complex dependencies, so we **strongly** recommend using a package manager such as [Miniconda](https://docs.anaconda.com/free/miniconda/) to install SLEAP in its own isolated environment. See the [Miniconda website](https://docs.anaconda.com/free/miniconda/) for installation instructions. The Anaconda or Mamba package managers will also work well; however, take care not to install multiple different conda-based package managers - choose one and stick with it. The newest version of SLEAP can always be found in the [Releases page](https://github.com/talmolab/sleap/releases). @@ -26,52 +26,8 @@ On Windows, our personal preference is to use alternative terminal apps like [Cm ```` -(apple-silicon)= - -### Macs Pre-M1 (Pre-Installation) - -SLEAP can be installed on Macs by following these instructions: - -1. Make sure you're on **macOS Monterey** or later, i.e., version 12+. - -2. If you don't have it yet, [install **homebrew**](https://brew.sh/), a convenient package manager for Macs (skip this if you can run `brew` from the terminal): - - ```bash - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - ``` - - This might take a little while since it'll also install Xcode (which we'll need later). Once it's finished, your terminal should give you two extra commands to run listed under **Next Steps**. - - ````{note} - We recommend running the commands given in your terminal which will be similar to (but may differ slightly) from the commands below: - ```bash - echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile - ``` - - ```bash - eval "$(/opt/homebrew/bin/brew shellenv)" - ``` - - ```` - - Then, close and re-open the terminal for it to take effect. - -3. Install wget, a CLI downloading utility (also makes sure your homebrew setup worked): - - ```bash - brew install wget - ``` - -(mambaforge)= - -## Installing Mambaforge - -**Anaconda** is a Python environment manager that makes it easy to install SLEAP and its necessary dependencies without affecting other Python software on your computer. - -[**Mambaforge**](https://mamba.readthedocs.io/en/latest/installation.html) is a lightweight installer of Anaconda with speedy package resolution that we recommend. - ````{note} -If you already have Anaconda on your computer, then you can [set the solver to `libmamba`](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community) in the `base` environment (and skip the Mambaforge installation): +If you already have Anaconda on your computer (and it is an [older installation](https://conda.org/blog/2023-11-06-conda-23-10-0-release/)), then make sure to [set the solver to `libmamba`](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community) in the `base` environment. ```bash conda update -n base conda @@ -85,75 +41,48 @@ Any subsequent `mamba` commands in the docs will need to be replaced with `conda ```` -Otherwise, to install Mamba: - -**On Windows**, just click through the installation steps. - -1. Go to: https://github.com/conda-forge/miniforge#mambaforge -2. Download the latest version for your OS. -3. Follow the installer instructions. - -We recommend using the following settings: - -- Install for: All Users (requires admin privileges) -- Destination folder: `C:\mambaforge` -- Advanced Options: Add MambaForge to the system PATH environment variable -- Advanced Options: Register MambaForge as the system Python 3.X - These will make sure that MambaForge is easily accessible from most places on your computer. - -**On Linux**, it might be easier to do this straight from the terminal (Ctrl + Alt + T) with this one-liner: - -```bash -wget -nc https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh && bash Mambaforge-Linux-x86_64.sh -b && ~/mambaforge/bin/conda init bash -``` - -Restart the terminal after running this command. - -```{note} -For other Linux architectures (arm64 and POWER8/9), replace the `.sh` filenames above with the correct installer name for your architecture. See the Download column in [this table](https://github.com/conda-forge/miniforge#mambaforge) for the correct filename. +## Installation methods -``` +SLEAP can be installed three different ways: via {ref}`conda package`, {ref}`conda from source`, or {ref}`pip package`. Select one of the methods below to install SLEAP. We recommend {ref}`conda package`. -**On Macs (pre-M1)**, you can run the installer using this terminal command: +(condapackage)= -```bash -wget -nc https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-MacOSX-x86_64.sh && bash Mambaforge-MacOSX-x86_64.sh -b && ~/mambaforge/bin/conda init zsh -``` +### `conda` package -**On Macs (Apple Silicon)**, use this terminal command: +````{tabs} -```bash -curl -fsSL --compressed https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-MacOSX-arm64.sh -o Mambaforge3-MacOSX-arm64.sh && chmod +x Mambaforge3-MacOSX-arm64.sh && ./Mambaforge3-MacOSX-arm64.sh -b -p ~/mambaforge3 && rm Mambaforge3-MacOSX-arm64.sh && ~/mambaforge3/bin/conda init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc" -``` + ```{tab} Windows and Linux -## Installation methods -SLEAP can be installed three different ways: via {ref}`conda package`, {ref}`conda from source`, or {ref}`pip package`. Select one of the methods below to install SLEAP. We recommend {ref}`conda package`. + ```bash + mamba create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 + ``` -(condapackage)= + + ```{note} + - This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and [updated drivers](https://nvidia.com/drivers). + - If you already have CUDA installed on your system, this will not conflict with it. + - This will also work in CPU mode if you don't have a GPU on your machine. + ``` -### `conda` package + ``` -**Windows** and **Linux** + ```{tab} Mac OS -```bash -mamba create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 -``` + ```bash + mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 + ``` -**Mac OS X** and **Apple Silicon** + ```{note} + This will also work in CPU mode if you don't have a GPU on your machine. + ``` + + ``` -```bash -mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 -``` +```` **This is the recommended installation method**. -```{note} -- This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and [updated drivers](https://nvidia.com/drivers). -- If you already have CUDA installed on your system, this will not conflict with it. -- This will also work in CPU mode if you don't have a GPU on your machine. -``` - (condasource)= ### `conda` from source @@ -172,25 +101,45 @@ mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 git clone https://github.com/talmolab/sleap && cd sleap ``` -3. Finally, install from the environment file (differs based on OS and GPU): +3. Finally, install SLEAP from the environment file: - **Windows** and **Linux** - ```bash - mamba env create -f environment.yml -n sleap - ``` + ````{tabs} - If you do not have a NVIDIA GPU, then you should use the no CUDA environment file: + ```{tab} Windows and Linux - ```bash - mamba env create -f environment_no_cuda.yml -n sleap - ``` + + ````{tabs} - **Mac OS X** and **Apple Silicon** + ```{tab} NVIDIA GPU + + ```bash + mamba env create -f environment.yml -n sleap + ``` + + ``` + + ```{tab} CPU or other GPU + + ```bash + mamba env create -f environment_no_cuda.yml -n sleap + ``` + + ``` + + ```` + + ``` + + ```{tab} Mac OS + + ```bash + mamba env create -f environment_mac.yml -n sleap + ``` + ``` + + ```` - ```bash - mamba env create -f environment_mac.yml -n sleap - ``` This is the **recommended method for development**. @@ -203,21 +152,31 @@ mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 ### `pip` package -Although you do not need Mambaforge installed to perform a `pip install`, we recommend {ref}`installing Mambaforge` to create a new environment where we can isolate the `pip install`. Alternatively, you can use a venv if you have an existing python installation. If you are working on **Google Colab**, skip to step 3 to perform the `pip install` without using a conda environment. +Although you do not need Mambaforge installed to perform a `pip install`, we recommend [installing Miniconda](https://docs.anaconda.com/free/miniconda/) to create a new environment where we can isolate the `pip install`. Alternatively, you can use a venv if you have an existing python installation. If you are working on **Google Colab**, skip to step 3 to perform the `pip install` without using a conda environment. 1. Otherwise, create a new conda environment where we will `pip install sleap`: - either without GPU support: + ````{tabs} - ```bash - mamba create --name sleap pip python=3.7.12 - ``` + ```{tab} NVIDIA GPU - or with GPU support: - ```bash - mamba create --name sleap pip python=3.7.12 cudatoolkit=11.3 cudnn=8.2 - ``` + ```bash + mamba create --name sleap pip python=3.7.12 cudatoolkit=11.3 cudnn=8.2 + ``` + + ``` + + ```{tab} CPU or other GPU + + ```bash + mamba create --name sleap pip python=3.7.12 + ``` + + + ``` + + ```` 2. Then activate the environment to isolate the `pip install` from other environments on your computer: From 2e4e74b20292ff9cca9385bfa88728f7acdff428 Mon Sep 17 00:00:00 2001 From: roomrys <38435167+roomrys@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:32:29 -0700 Subject: [PATCH 03/16] Move installation methods to tabs --- docs/_static/css/tabs.css | 89 +++++++++++++ docs/conf.py | 10 ++ docs/installation.md | 263 ++++++++++++++++++++++---------------- 3 files changed, 250 insertions(+), 112 deletions(-) create mode 100644 docs/_static/css/tabs.css diff --git a/docs/_static/css/tabs.css b/docs/_static/css/tabs.css new file mode 100644 index 000000000..5c8708f75 --- /dev/null +++ b/docs/_static/css/tabs.css @@ -0,0 +1,89 @@ +.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: var(--bs-body-color); + 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(50, 50, 50); + margin: -1px; + background-color: rgb(50, 50, 50); + } + + .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(50, 50, 50); + } + + .sphinx-tabs-panel.code-tab { + padding: 0.4rem; + } + + .sphinx-tab img { + margin-bottom: 24 px; + } + + /* Dark theme preference styling */ + + @media (prefers-color-scheme: dark) { + body[data-theme="auto"] .sphinx-tabs-panel { + color: white; + background-color: rgb(50, 50, 50); + } + + body[data-theme="auto"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); + } + + body[data-theme="auto"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 1px solid rgb(50, 50, 50); + background-color: rgb(50, 50, 50); + } + } + + /* Explicit dark theme styling */ + + body[data-theme="dark"] .sphinx-tabs-panel { + color: white; + background-color: rgb(50, 50, 50); + } + + body[data-theme="dark"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); + } + + body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 2px solid rgb(50, 50, 50); + background-color: rgb(50, 50, 50); + } \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 9bdfdcfb6..226d48494 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -174,6 +174,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/custom.css', +] + # Custom sidebar templates, must be a dictionary that maps document names # to template names. # @@ -220,3 +226,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 diff --git a/docs/installation.md b/docs/installation.md index 462fb0010..f9a0431f3 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,8 +2,6 @@ SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. -SLEAP requires many complex dependencies, so we **strongly** recommend using a package manager such as [Miniconda](https://docs.anaconda.com/free/miniconda/) to install SLEAP in its own isolated environment. See the [Miniconda website](https://docs.anaconda.com/free/miniconda/) for installation instructions. The Anaconda or Mamba package managers will also work well; however, take care not to install multiple different conda-based package managers - choose one and stick with it. - The newest version of SLEAP can always be found in the [Releases page](https://github.com/talmolab/sleap/releases). ```{contents} Contents @@ -12,19 +10,10 @@ local: --- ``` -````{hint} -Installation requires entering commands in a terminal. To open one: - -**Windows:** Open the *Start menu* and search for the *Miniforge Prompt* (if using Mambaforge) or the *Command Prompt* if not. -```{note} -On Windows, our personal preference is to use alternative terminal apps like [Cmder](https://cmder.net) or [Windows Terminal](https://aka.ms/terminal). -``` - -**Linux:** Launch a new terminal by pressing Ctrl + Alt + T. -**Mac:** Launch a new terminal by pressing Cmd + Space and searching for _Terminal_. +## Package Manager -```` +SLEAP requires many complex dependencies, so we **strongly** recommend using a package manager such as [Miniconda](https://docs.anaconda.com/free/miniconda/) to install SLEAP in its own isolated environment. See the [Miniconda website](https://docs.anaconda.com/free/miniconda/) for installation instructions. The Anaconda or Mamba package managers will also work well; however, take care not to install multiple different conda-based package managers - choose one and stick with it. ````{note} If you already have Anaconda on your computer (and it is an [older installation](https://conda.org/blog/2023-11-06-conda-23-10-0-release/)), then make sure to [set the solver to `libmamba`](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community) in the `base` environment. @@ -45,177 +34,227 @@ Any subsequent `mamba` commands in the docs will need to be replaced with `conda SLEAP can be installed three different ways: via {ref}`conda package`, {ref}`conda from source`, or {ref}`pip package`. Select one of the methods below to install SLEAP. We recommend {ref}`conda package`. -(condapackage)= -### `conda` package -````{tabs} +`````{hint} + Installation requires entering commands in a terminal. To open one: - ```{tab} Windows and Linux + ````{tabs} + ```{tab} Windows - ```bash - mamba create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 - ``` + Open the *Start menu* and search for the *Anaconda Prompt* (if using Miniconda) or the *Command Prompt* if not. + + ```{note} + On Windows, our personal preference is to use alternative terminal apps like [Cmder](https://cmder.net) or [Windows Terminal](https://aka.ms/terminal). + ``` - - ```{note} - - This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and [updated drivers](https://nvidia.com/drivers). - - If you already have CUDA installed on your system, this will not conflict with it. - - This will also work in CPU mode if you don't have a GPU on your machine. ``` - ``` + ```{tab} Linux - ```{tab} Mac OS + Launch a new terminal by pressing Ctrl + Alt + T. - ```bash - mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 ``` - ```{note} - This will also work in CPU mode if you don't have a GPU on your machine. + ```{group-tab} Mac OS + + Launch a new terminal by pressing Cmd + Space and searching for _Terminal_. + ``` - - ``` -```` + ```` -**This is the recommended installation method**. +````` -(condasource)= +````{tabs} -### `conda` from source + ```{tab} conda package -1. First, ensure git is installed: + **This is the recommended installation method**. - ```bash - git --version - ``` + ````{tabs} - If 'git' is not recognized, then [install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). + ```{group-tab} Windows and Linux -2. Then, clone the repository: - ```bash - git clone https://github.com/talmolab/sleap && cd sleap + ```bash + mamba create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 + ``` + + + ```{note} + - This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and [updated drivers](https://nvidia.com/drivers). + - If you already have CUDA installed on your system, this will not conflict with it. + - This will also work in CPU mode if you don't have a GPU on your machine. + ``` + + ``` + + ```{group-tab} Mac OS + + ```bash + mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 + ``` + + ```{note} + This will also work in CPU mode if you don't have a GPU on your machine. + ``` + + ``` + + ```` + ``` -3. Finally, install SLEAP from the environment file: + ```{tab} conda from source + This is the **recommended method for development**. - ````{tabs} + 1. First, ensure git is installed: + + ```bash + git --version + ``` + + If `git` is not recognized, then [install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). + + 2. Then, clone the repository: + + ```bash + git clone https://github.com/talmolab/sleap && cd sleap + ``` + + 3. Finally, install SLEAP from the environment file: - ```{tab} Windows and Linux - ````{tabs} - ```{tab} NVIDIA GPU + ```{group-tab} Windows and Linux - ```bash - mamba env create -f environment.yml -n sleap - ``` + + ````{tabs} + + ```{group-tab} NVIDIA GPU + + ```bash + mamba env create -f environment.yml -n sleap + ``` + + ``` + + ```{group-tab} CPU or other GPU + + ```bash + mamba env create -f environment_no_cuda.yml -n sleap + ``` + + ``` + + ```` ``` - ```{tab} CPU or other GPU + ```{group-tab} Mac OS ```bash - mamba env create -f environment_no_cuda.yml -n sleap + mamba env create -f environment_mac.yml -n sleap ``` - ``` ```` + ```{note} + - This installs SLEAP in development mode, which means that edits to the source code will be applied the next time you run SLEAP. + - Change the `-n sleap` in the command to create an environment with a different name (e.g., `-n sleap_develop`). ``` + + ``` - ```{tab} Mac OS + ```{tab} pip package - ```bash - mamba env create -f environment_mac.yml -n sleap - ``` - ``` + This is the **recommended method for Google Colab only**. - ```` + ```{warning} + This will uninstall existing libraries and potentially install conflicting ones. + We strongly recommend that you **only use this method if you know what you're doing**! + ``` - This is the **recommended method for development**. + ````{tabs} -```{note} -- This installs SLEAP in development mode, which means that edits to the source code will be applied the next time you run SLEAP. -- Change the `-n sleap` in the command to create an environment with a different name (e.g., `-n sleap_develop`). -``` + ```{group-tab} Windows and Linux -(pippackage)= + ```{note} + - Requires Python 3.7 + - To enable GPU support, make sure that you have **CUDA Toolkit v11.3** and **cuDNN v8.2** installed. + ``` -### `pip` package + Although you do not need Miniconda installed to perform a `pip install`, we recommend [installing Miniconda](https://docs.anaconda.com/free/miniconda/) to create a new environment where we can isolate the `pip install`. Alternatively, you can use a venv if you have an existing Python 3.7 installation. If you are working on **Google Colab**, skip to step 3 to perform the `pip install` without using a conda environment. -Although you do not need Mambaforge installed to perform a `pip install`, we recommend [installing Miniconda](https://docs.anaconda.com/free/miniconda/) to create a new environment where we can isolate the `pip install`. Alternatively, you can use a venv if you have an existing python installation. If you are working on **Google Colab**, skip to step 3 to perform the `pip install` without using a conda environment. + 1. Otherwise, create a new conda environment where we will `pip install sleap`: -1. Otherwise, create a new conda environment where we will `pip install sleap`: + ````{tabs} - ````{tabs} + ```{group-tab} NVIDIA GPU - ```{tab} NVIDIA GPU + ```bash + mamba create --name sleap pip python=3.7.12 cudatoolkit=11.3 cudnn=8.2 + ``` - ```bash - mamba create --name sleap pip python=3.7.12 cudatoolkit=11.3 cudnn=8.2 - ``` + ``` - ``` + ```{group-tab} CPU or other GPU - ```{tab} CPU or other GPU + ```bash + mamba create --name sleap pip python=3.7.12 + ``` - ```bash - mamba create --name sleap pip python=3.7.12 - ``` - - - ``` + + ``` - ```` + ```` -2. Then activate the environment to isolate the `pip install` from other environments on your computer: + 2. Then activate the environment to isolate the `pip install` from other environments on your computer: - ```bash - mamba activate sleap - ``` + ```bash + mamba activate sleap + ``` - ```{warning} - Refrain from installing anything into the `base` environment. Always create a new environment to install new packages. - ``` + ```{warning} + Refrain from installing anything into the `base` environment. Always create a new environment to install new packages. + ``` -3. Finally, we can perform the `pip install`: + 3. Finally, we can perform the `pip install`: - ```bash - pip install sleap[pypi]==1.4.1a1 - ``` + ```bash + pip install sleap[pypi]==1.4.1a1 + ``` - This works on **any OS except Apple silicon** and on **Google Colab**. + ```{note} + The pypi distributed package of SLEAP ships with the following extras: + - **pypi**: For installation without an mamba environment file. All dependencies come from PyPI. + - **jupyter**: This installs all *pypi* and jupyter lab dependencies. + - **dev**: This installs all *jupyter* dependencies and developement tools for testing and building docs. + - **conda_jupyter**: For installation using a mamba environment file included in the source code. Most dependencies are listed as conda packages in the environment file and only a few come from PyPI to allow jupyter lab support. + - **conda_dev**: For installation using [a mamba environment](https://github.com/search?q=repo%3Atalmolab%2Fsleap+path%3Aenvironment*.yml&type=code) with a few PyPI dependencies for development tools. + ``` + + ``` - ```{note} - The pypi distributed package of SLEAP ships with the following extras: - - **pypi**: For installation without an mamba environment file. All dependencies come from PyPI. - - **jupyter**: This installs all *pypi* and jupyter lab dependencies. - - **dev**: This installs all *jupyter* dependencies and developement tools for testing and building docs. - - **conda_jupyter**: For installation using a mamba environment file included in the source code. Most dependencies are listed as conda packages in the environment file and only a few come from PyPI to allow jupyter lab support. - - **conda_dev**: For installation using [a mamba environment](https://github.com/search?q=repo%3Atalmolab%2Fsleap+path%3Aenvironment*.yml&type=code) with a few PyPI dependencies for development tools. - ``` + ```{group-tab} Mac OS - ```{note} - - Requires Python 3.7 - - To enable GPU support, make sure that you have **CUDA Toolkit v11.3** and **cuDNN v8.2** installed. - ``` + Not supported. - ```{warning} - This will uninstall existing libraries and potentially install conflicting ones. + ``` - We strongly recommend that you **only use this method if you know what you're doing**! + ```` + ``` +```` + ## Testing that things are working If you installed using `mamba`, first activate the `sleap` environment by opening a terminal and typing: From 35e13eae720f20ade3ecb2b9a91c39f4d93f0b5c Mon Sep 17 00:00:00 2001 From: roomrys <38435167+roomrys@users.noreply.github.com> Date: Mon, 24 Jun 2024 10:01:38 -0700 Subject: [PATCH 04/16] Use tabs.css --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 226d48494..5f00045dc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -177,7 +177,7 @@ def linkcode_resolve(domain, info): # These paths are either relative to html_static_path # or fully qualified paths (eg. https://...) html_css_files = [ - 'css/custom.css', + 'css/tabs.css', ] # Custom sidebar templates, must be a dictionary that maps document names From 01abcb7b5fd9ec7fe7462d0db54ae4b254083827 Mon Sep 17 00:00:00 2001 From: roomrys <38435167+roomrys@users.noreply.github.com> Date: Mon, 24 Jun 2024 11:07:35 -0700 Subject: [PATCH 05/16] FIx styling error (line under last tab in terminal hint) --- docs/_static/css/tabs.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/_static/css/tabs.css b/docs/_static/css/tabs.css index 5c8708f75..10914e8a4 100644 --- a/docs/_static/css/tabs.css +++ b/docs/_static/css/tabs.css @@ -28,6 +28,10 @@ margin: -1px; background-color: rgb(50, 50, 50); } + + .admonition .sphinx-tabs-tab[aria-selected="true"]:last-child { + margin-bottom: -1px; + } .sphinx-tabs-tab:focus { z-index: 1; From 857bcd43fa52df31e7fcbe98d4e8c51acec7786f Mon Sep 17 00:00:00 2001 From: roomrys <38435167+roomrys@users.noreply.github.com> Date: Mon, 24 Jun 2024 11:08:46 -0700 Subject: [PATCH 06/16] Add installation instructions before TOC --- docs/installation.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/installation.md b/docs/installation.md index f9a0431f3..7b7fb46f1 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,6 +2,38 @@ SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. +````{tabs} + + ```{group-tab} Windows and Linux + + + ```bash + mamba create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 + ``` + + + ```{note} + - This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and [updated drivers](https://nvidia.com/drivers). + - If you already have CUDA installed on your system, this will not conflict with it. + - This will also work in CPU mode if you don't have a GPU on your machine. + ``` + + ``` + + ```{group-tab} Mac OS + + ```bash + mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 + ``` + + ```{note} + This will also work in CPU mode if you don't have a GPU on your machine. + ``` + + ``` + +```` + The newest version of SLEAP can always be found in the [Releases page](https://github.com/talmolab/sleap/releases). ```{contents} Contents From d3ca0ed1cefc2ce3f54d50578b5ae109107c4a45 Mon Sep 17 00:00:00 2001 From: roomrys <38435167+roomrys@users.noreply.github.com> Date: Mon, 24 Jun 2024 11:25:11 -0700 Subject: [PATCH 07/16] Replace mamba with conda --- .conda/README.md | 4 ++-- docs/installation.md | 50 ++++++++++++++++++++++---------------------- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/.conda/README.md b/.conda/README.md index 71a49d7f1..65fadd36e 100644 --- a/.conda/README.md +++ b/.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. diff --git a/docs/installation.md b/docs/installation.md index 7b7fb46f1..391f31bff 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -8,7 +8,7 @@ SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. ```bash - mamba create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 + conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 ``` @@ -23,7 +23,7 @@ SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. ```{group-tab} Mac OS ```bash - mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 + conda create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 ``` ```{note} @@ -57,7 +57,7 @@ conda config --set solver libmamba ``` ```{warning} -Any subsequent `mamba` commands in the docs will need to be replaced with `conda` if you choose to use your existing Anaconda installation. +Any subsequent `conda` commands in the docs will need to be replaced with `mamba` if you have [Mamba](https://mamba.readthedocs.io/en/latest/) installed instead of Anaconda or Miniconda. ``` ```` @@ -111,7 +111,7 @@ SLEAP can be installed three different ways: via {ref}`conda package Date: Mon, 24 Jun 2024 11:47:40 -0700 Subject: [PATCH 08/16] Lint --- docs/installation.md | 148 ++++++------------------------------------- 1 file changed, 21 insertions(+), 127 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 391f31bff..e50b19e18 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,40 +1,21 @@ # Installation -SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. +SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. For quick install using conda, see below: ````{tabs} - ```{group-tab} Windows and Linux - - ```bash conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 ``` - - - ```{note} - - This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and [updated drivers](https://nvidia.com/drivers). - - If you already have CUDA installed on your system, this will not conflict with it. - - This will also work in CPU mode if you don't have a GPU on your machine. - ``` - ``` - ```{group-tab} Mac OS - ```bash conda create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 ``` - - ```{note} - This will also work in CPU mode if you don't have a GPU on your machine. - ``` - ``` - ```` -The newest version of SLEAP can always be found in the [Releases page](https://github.com/talmolab/sleap/releases). +. For more in-depth installation instructions, see the [installation methods](installation-methods). The newest version of SLEAP can always be found in the [Releases page](https://github.com/talmolab/sleap/releases). ```{contents} Contents --- @@ -42,6 +23,23 @@ local: --- ``` +`````{hint} + Installation requires entering commands in a terminal. To open one: + ````{tabs} + ```{tab} Windows + Open the *Start menu* and search for the *Anaconda Prompt* (if using Miniconda) or the *Command Prompt* if not. + ```{note} + On Windows, our personal preference is to use alternative terminal apps like [Cmder](https://cmder.net) or [Windows Terminal](https://aka.ms/terminal). + ``` + ``` + ```{tab} Linux + Launch a new terminal by pressing Ctrl + Alt + T. + ``` + ```{group-tab} Mac OS + Launch a new terminal by pressing Cmd + Space and searching for _Terminal_. + ``` + ```` +````` ## Package Manager @@ -62,208 +60,111 @@ Any subsequent `conda` commands in the docs will need to be replaced with `mamba ```` +(installation-methods)= ## Installation methods SLEAP can be installed three different ways: via {ref}`conda package`, {ref}`conda from source`, or {ref}`pip package`. Select one of the methods below to install SLEAP. We recommend {ref}`conda package`. - - -`````{hint} - Installation requires entering commands in a terminal. To open one: - - ````{tabs} - - ```{tab} Windows - - Open the *Start menu* and search for the *Anaconda Prompt* (if using Miniconda) or the *Command Prompt* if not. - - ```{note} - On Windows, our personal preference is to use alternative terminal apps like [Cmder](https://cmder.net) or [Windows Terminal](https://aka.ms/terminal). - ``` - - ``` - - ```{tab} Linux - - Launch a new terminal by pressing Ctrl + Alt + T. - - ``` - - ```{group-tab} Mac OS - - Launch a new terminal by pressing Cmd + Space and searching for _Terminal_. - - ``` - - ```` - -````` - ````{tabs} - ```{tab} conda package - **This is the recommended installation method**. - ````{tabs} - ```{group-tab} Windows and Linux - - ```bash conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1 - ``` - - + ``` ```{note} - This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and [updated drivers](https://nvidia.com/drivers). - If you already have CUDA installed on your system, this will not conflict with it. - This will also work in CPU mode if you don't have a GPU on your machine. ``` - ``` - ```{group-tab} Mac OS - ```bash conda create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1 ``` - ```{note} This will also work in CPU mode if you don't have a GPU on your machine. ``` - ``` - ```` - ``` - ```{tab} conda from source - This is the **recommended method for development**. - 1. First, ensure git is installed: - ```bash git --version ``` - If `git` is not recognized, then [install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). - 2. Then, clone the repository: - ```bash git clone https://github.com/talmolab/sleap && cd sleap ``` - 3. Finally, install SLEAP from the environment file: - - ````{tabs} - ```{group-tab} Windows and Linux - - ````{tabs} - ```{group-tab} NVIDIA GPU - ```bash conda env create -f environment.yml -n sleap ``` - ``` - ```{group-tab} CPU or other GPU - ```bash conda env create -f environment_no_cuda.yml -n sleap ``` - ``` - ```` - ``` - ```{group-tab} Mac OS - ```bash conda env create -f environment_mac.yml -n sleap ``` ``` - ```` - ```{note} - This installs SLEAP in development mode, which means that edits to the source code will be applied the next time you run SLEAP. - Change the `-n sleap` in the command to create an environment with a different name (e.g., `-n sleap_develop`). ``` - ``` - ```{tab} pip package - This is the **recommended method for Google Colab only**. - ```{warning} This will uninstall existing libraries and potentially install conflicting ones. We strongly recommend that you **only use this method if you know what you're doing**! ``` - ````{tabs} - ```{group-tab} Windows and Linux - ```{note} - Requires Python 3.7 - To enable GPU support, make sure that you have **CUDA Toolkit v11.3** and **cuDNN v8.2** installed. ``` - Although you do not need Miniconda installed to perform a `pip install`, we recommend [installing Miniconda](https://docs.anaconda.com/free/miniconda/) to create a new environment where we can isolate the `pip install`. Alternatively, you can use a venv if you have an existing Python 3.7 installation. If you are working on **Google Colab**, skip to step 3 to perform the `pip install` without using a conda environment. - 1. Otherwise, create a new conda environment where we will `pip install sleap`: - ````{tabs} - ```{group-tab} NVIDIA GPU - - ```bash conda create --name sleap pip python=3.7.12 cudatoolkit=11.3 cudnn=8.2 ``` - ``` - ```{group-tab} CPU or other GPU - ```bash conda create --name sleap pip python=3.7.12 ``` - - ``` - ```` - 2. Then activate the environment to isolate the `pip install` from other environments on your computer: - ```bash conda activate sleap ``` - ```{warning} Refrain from installing anything into the `base` environment. Always create a new environment to install new packages. ``` - 3. Finally, we can perform the `pip install`: - ```bash pip install sleap[pypi]==1.4.1a1 ``` - ```{note} The pypi distributed package of SLEAP ships with the following extras: - **pypi**: For installation without an conda environment file. All dependencies come from PyPI. @@ -272,19 +173,12 @@ SLEAP can be installed three different ways: via {ref}`conda package Date: Thu, 5 Sep 2024 14:02:00 -0700 Subject: [PATCH 09/16] Find good light colors not switching when change dark/light themes --- docs/_static/css/tabs.css | 158 +++++++++++++++++++------------------- 1 file changed, 80 insertions(+), 78 deletions(-) diff --git a/docs/_static/css/tabs.css b/docs/_static/css/tabs.css index 10914e8a4..a96a6e6e1 100644 --- a/docs/_static/css/tabs.css +++ b/docs/_static/css/tabs.css @@ -1,82 +1,64 @@ .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: var(--bs-body-color); - 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(50, 50, 50); - margin: -1px; - background-color: rgb(50, 50, 50); - } + margin-bottom: 1rem; +} - .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(50, 50, 50); - } - - .sphinx-tabs-panel.code-tab { - padding: 0.4rem; - } - - .sphinx-tab img { - margin-bottom: 24 px; - } - - /* Dark theme preference styling */ - - @media (prefers-color-scheme: dark) { - body[data-theme="auto"] .sphinx-tabs-panel { - color: white; - background-color: rgb(50, 50, 50); - } - - body[data-theme="auto"] .sphinx-tabs-tab { - color: white; - background-color: rgba(255, 255, 255, 0.05); - } - - body[data-theme="auto"] .sphinx-tabs-tab[aria-selected="true"] { - border-bottom: 1px solid rgb(50, 50, 50); - background-color: rgb(50, 50, 50); - } - } - - /* Explicit dark theme styling */ - +[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: 24 px; +} + +/* Dark theme preference styling */ + +@media (prefers-color-scheme: dark) { body[data-theme="dark"] .sphinx-tabs-panel { color: white; background-color: rgb(50, 50, 50); @@ -90,4 +72,24 @@ body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] { border-bottom: 2px solid rgb(50, 50, 50); background-color: rgb(50, 50, 50); - } \ No newline at end of file + } +} + +/* Light theme preference styling */ + +@media (prefers-color-scheme: light) { + body[data-theme="light"] .sphinx-tabs-panel { + color: rgb(50, 50, 50); + background-color: rgb(220, 231, 252); + } + + body[data-theme="light"] .sphinx-tabs-tab { + color: white; + background-color: rgba(255, 255, 255, 0.05); + } + + body[data-theme="light"] .sphinx-tabs-tab[aria-selected="true"] { + border-bottom: 2px solid rgb(220, 231, 252); + background-color: rgb(220, 231, 252); + } +} \ No newline at end of file From 898ed797d7dda17814691069db0744d3487a14fa Mon Sep 17 00:00:00 2001 From: roomrys Date: Thu, 5 Sep 2024 14:24:12 -0700 Subject: [PATCH 10/16] Get color scheme switching with dark/light toggle button --- docs/_static/css/tabs.css | 56 ++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/docs/_static/css/tabs.css b/docs/_static/css/tabs.css index a96a6e6e1..095c522a8 100644 --- a/docs/_static/css/tabs.css +++ b/docs/_static/css/tabs.css @@ -58,38 +58,34 @@ /* Dark theme preference styling */ -@media (prefers-color-scheme: dark) { - body[data-theme="dark"] .sphinx-tabs-panel { - color: white; - background-color: rgb(50, 50, 50); - } - - body[data-theme="dark"] .sphinx-tabs-tab { - color: white; - background-color: rgba(255, 255, 255, 0.05); - } - - body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] { - border-bottom: 2px solid rgb(50, 50, 50); - background-color: rgb(50, 50, 50); - } +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 */ -@media (prefers-color-scheme: light) { - body[data-theme="light"] .sphinx-tabs-panel { - color: rgb(50, 50, 50); - background-color: rgb(220, 231, 252); - } - - body[data-theme="light"] .sphinx-tabs-tab { - color: white; - background-color: rgba(255, 255, 255, 0.05); - } - - body[data-theme="light"] .sphinx-tabs-tab[aria-selected="true"] { - border-bottom: 2px solid rgb(220, 231, 252); - background-color: rgb(220, 231, 252); - } +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; } \ No newline at end of file From 05d294a6bca98a4e61ec5b2488773c4c642ff5d2 Mon Sep 17 00:00:00 2001 From: roomrys Date: Thu, 5 Sep 2024 14:25:55 -0700 Subject: [PATCH 11/16] Upgrade website build dependencies --- dev_requirements.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/dev_requirements.txt b/dev_requirements.txt index f7bb23643..c5f5740b1 100644 --- a/dev_requirements.txt +++ b/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 +myst-parser linkify-it-py sphinx-autobuild black==21.6b0 From 63ecaf792bd2cc791b1b58509838ba4df47f6af0 Mon Sep 17 00:00:00 2001 From: roomrys Date: Thu, 5 Sep 2024 14:26:16 -0700 Subject: [PATCH 12/16] Remove seemingly unneeded dependencies from workflow --- .github/workflows/website.yml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 453f331a0..4a6d6505a 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -36,13 +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] - pip install sphinx-tabs cd docs python make_api_doctree.py make html @@ -63,4 +58,4 @@ jobs: github_token: ${{ secrets.GITHUB_TOKEN }} publish_branch: gh-pages publish_dir: docs/build/html - destination_dir: develop \ No newline at end of file + destination_dir: develop From b7446cbbc54599b7e4f10b5380809c34c081b1ed Mon Sep 17 00:00:00 2001 From: roomrys Date: Thu, 5 Sep 2024 14:39:03 -0700 Subject: [PATCH 13/16] Add myst-nb>=0.16.0 lower bound --- dev_requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev_requirements.txt b/dev_requirements.txt index c5f5740b1..709fb48fd 100644 --- a/dev_requirements.txt +++ b/dev_requirements.txt @@ -11,7 +11,7 @@ sphinx-book-theme sphinx-copybutton sphinx-tabs nbformat==5.1.3 -myst-nb +myst-nb>=0.16.0 # sphinx>=5.0 needs myst-nb>=0.16.0 myst-parser linkify-it-py sphinx-autobuild From 8958473cfdc3392b6c866013a0cfc7f022729620 Mon Sep 17 00:00:00 2001 From: roomrys Date: Thu, 5 Sep 2024 14:44:46 -0700 Subject: [PATCH 14/16] Trigger dev website build --- .github/workflows/website.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 4a6d6505a..ede9eef9f 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -8,7 +8,7 @@ on: # 'main' triggers updates to 'sleap.ai', all others to 'sleap.ai/develop' - main - develop - - liezl/update-intallation-docs-1.4.1 + - liezl/update-intallation-docs-1.4.1 # again! paths: - "docs/**" - "README.rst" From 930d94eed4c79ba263d44ffd7206b9b3be217b93 Mon Sep 17 00:00:00 2001 From: roomrys Date: Thu, 5 Sep 2024 15:06:09 -0700 Subject: [PATCH 15/16] Fix minor typo in css --- docs/_static/css/tabs.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_static/css/tabs.css b/docs/_static/css/tabs.css index 095c522a8..95765dff6 100644 --- a/docs/_static/css/tabs.css +++ b/docs/_static/css/tabs.css @@ -53,7 +53,7 @@ } .sphinx-tab img { - margin-bottom: 24 px; + margin-bottom: 24px; } /* Dark theme preference styling */ From 87d05b429245ca46b4e6bb534f74f70f9a5e390a Mon Sep 17 00:00:00 2001 From: Talmo Pereira Date: Fri, 6 Sep 2024 11:14:32 -0700 Subject: [PATCH 16/16] Add miniforge and one-liner installs for package managers --- docs/installation.md | 78 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index 913f87b21..4799a0893 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -43,7 +43,7 @@ local: ## Package Manager -SLEAP requires many complex dependencies, so we **strongly** recommend using a package manager such as [Miniconda](https://docs.anaconda.com/free/miniconda/) to install SLEAP in its own isolated environment. See the [Miniconda website](https://docs.anaconda.com/free/miniconda/) for installation instructions. The Anaconda or Mamba package managers will also work well; however, take care not to install multiple different conda-based package managers - choose one and stick with it. +SLEAP requires many complex dependencies, so we **strongly** recommend using a package manager such as [Miniforge](https://github.com/conda-forge/miniforge) or [Miniconda](https://docs.anaconda.com/free/miniconda/) to install SLEAP in its own isolated environment. ````{note} If you already have Anaconda on your computer (and it is an [older installation](https://conda.org/blog/2023-11-06-conda-23-10-0-release/)), then make sure to [set the solver to `libmamba`](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community) in the `base` environment. @@ -60,6 +60,82 @@ Any subsequent `conda` commands in the docs will need to be replaced with `mamba ```` +If you don't have a `conda` package manager installation, here are some quick install options: + +### Miniforge (recommended) + +Miniforge is a minimal installer for conda that includes the `conda` package manager and is maintained by the [conda-forge](https://conda-forge.org) community. The only difference between Miniforge and Miniconda is that Miniforge uses the `conda-forge` channel by default, which provides a much wider selection of community-maintained packages. + + +````{tabs} + ```{group-tab} Windows + Open a new PowerShell terminal (does not need to be admin) and enter: + + ```bash + Invoke-WebRequest -Uri "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe" -OutFile "$env:UserProfile/Downloads/Miniforge3-Windows-x86_64.exe"; Start-Process -FilePath "$env:UserProfile/Downloads/Miniforge3-Windows-x86_64.exe" -ArgumentList "/InstallationType=JustMe /RegisterPython=1 /S" -Wait; Remove-Item -Path "$env:UserProfile/Downloads/Miniforge3-Windows-x86_64.exe" + ``` + ``` + ```{group-tab} Linux + Open a new terminal and enter: + + ```bash + curl -fsSL --compressed https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -o "~/Downloads/Miniforge3-Linux-x86_64.sh" && chmod +x "~/Downloads/Miniforge3-Linux-x86_64.sh" && "~/Downloads/Miniforge3-Linux-x86_64.sh" -b -p ~/miniforge3 && rm "~/Downloads/Miniforge3-Linux-x86_64.sh" && ~/miniforge3/bin/conda init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc" + ``` + ``` + ```{group-tab} Mac (Apple Silicon) + Open a new terminal and enter: + + ```bash + curl -fsSL --compressed https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh -o "~/Downloads/Miniforge3-MacOSX-arm64.sh" && chmod +x "~/Downloads/Miniforge3-MacOSX-arm64.sh" && "~/Downloads/Miniforge3-MacOSX-arm64.sh" -b -p ~/miniforge3 && rm "~/Downloads/Miniforge3-MacOSX-arm64.sh" && ~/miniforge3/bin/conda init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc" + ``` + ``` + ```{group-tab} Mac (Intel) + Open a new terminal and enter: + + ```bash + curl -fsSL --compressed https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh -o "~/Downloads/Miniforge3-MacOSX-x86_64.sh" && chmod +x "~/Downloads/Miniforge3-MacOSX-x86_64.sh" && "~/Downloads/Miniforge3-MacOSX-x86_64.sh" -b -p ~/miniforge3 && rm "~/Downloads/Miniforge3-MacOSX-x86_64.sh" && ~/miniforge3/bin/conda init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc" + ``` + ``` +```` + +### Miniconda + +This is a minimal installer for conda that includes the `conda` package manager and is maintained by the [Anaconda](https://www.anaconda.com) company. + +````{tabs} + ```{group-tab} Windows + Open a new PowerShell terminal (does not need to be admin) and enter: + + ```bash + curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -o miniconda.exe; Start-Process -FilePath ".\miniconda.exe" -ArgumentList "/S" -Wait; del miniconda.exe + ``` + ``` + ```{group-tab} Linux + Open a new terminal and enter: + + ```bash + mkdir -p ~/miniconda3 && wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh && bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3 && rm ~/miniconda3/miniconda.sh && ~/miniconda3/bin/conda init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc" + ``` + ``` + ```{group-tab} Mac (Apple Silicon) + Open a new terminal and enter: + + ```bash + curl -fsSL --compressed https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o "~/Downloads/Miniconda3-latest-MacOSX-arm64.sh" && chmod +x "~/Downloads/Miniconda3-latest-MacOSX-arm64.sh" && "~/Downloads/Miniconda3-latest-MacOSX-arm64.sh" -b -u -p ~/miniconda3 && rm "~/Downloads/Miniconda3-latest-MacOSX-arm64.sh" && ~/miniconda3/bin/conda init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc" + ``` + ``` + ```{group-tab} Mac (Intel) + Open a new terminal and enter: + + ```bash + curl -fsSL --compressed https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o "~/Downloads/Miniconda3-latest-MacOSX-x86_64.sh" && chmod +x "~/Downloads/Miniconda3-latest-MacOSX-x86_64.sh" && "~/Downloads/Miniconda3-latest-MacOSX-x86_64.sh" -b -u -p ~/miniconda3 && rm "~/Downloads/Miniconda3-latest-MacOSX-x86_64.sh" && ~/miniconda3/bin/conda init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc" + ``` + ``` +```` + +See the [Miniconda website](https://docs.anaconda.com/free/miniconda/) for up-to-date installation instructions if the above instructions don't work for your system. + + (installation-methods)= ## Installation methods