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] 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: