From 83d6bc04ce3f0c93a8af9a7536db39c60affc1d8 Mon Sep 17 00:00:00 2001 From: MweinbergUmass <143860933+MweinbergUmass@users.noreply.github.com> Date: Wed, 4 Sep 2024 17:50:28 -0700 Subject: [PATCH 1/6] Option for Max Stride to be 128 (#1941) Co-authored-by: Max Weinberg --- sleap/config/training_editor_form.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sleap/config/training_editor_form.yaml b/sleap/config/training_editor_form.yaml index eabfc3940..7d7972892 100644 --- a/sleap/config/training_editor_form.yaml +++ b/sleap/config/training_editor_form.yaml @@ -44,7 +44,7 @@ model: label: Max Stride name: model.backbone.hourglass.max_stride type: list - options: 1,2,4,8,16,32,64 + options: 1,2,4,8,16,32,64,128 # - default: 4 # help: Determines the number of upsampling blocks in the network. # label: Output Stride @@ -81,7 +81,7 @@ model: label: Max Stride name: model.backbone.leap.max_stride type: list - options: 2,4,8,16,32,64 + options: 2,4,8,16,32,64,128 # - default: 1 # help: Determines the number of upsampling blocks in the network. # label: Output Stride @@ -190,7 +190,7 @@ model: label: Max Stride name: model.backbone.resnet.max_stride type: list - options: 2,4,8,16,32,64 + options: 2,4,8,16,32,64,128 # - default: 4 # help: Stride of the final output. If the upsampling branch is not defined, the # output stride is controlled via dilated convolutions or reduced pooling in the @@ -250,7 +250,7 @@ model: label: Max Stride name: model.backbone.unet.max_stride type: list - options: 2,4,8,16,32,64 + options: 2,4,8,16,32,64,128 # - default: 1 # help: Determines the number of upsampling blocks in the network. # label: Output Stride From 983a7840c3498f147e01e83b4e82efb5e0f3ae90 Mon Sep 17 00:00:00 2001 From: Liezl Maree <38435167+roomrys@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:47:44 -0700 Subject: [PATCH 2/6] Add discussion comment workflow (#1945) * Add a bot to autocomment on workflow * Use github markdown warning syntax * Add a multiline warning * Change happy coding to happy SLEAPing Co-authored-by: Talmo Pereira --------- Co-authored-by: roomrys Co-authored-by: Talmo Pereira --- .github/workflows/comment.yml | 50 +++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 .github/workflows/comment.yml diff --git a/.github/workflows/comment.yml b/.github/workflows/comment.yml new file mode 100644 index 000000000..39423ad54 --- /dev/null +++ b/.github/workflows/comment.yml @@ -0,0 +1,50 @@ +name: Comment on New Discussions + +on: + discussion: + types: [created] + +jobs: + comment: + runs-on: ubuntu-latest + + steps: + - name: Post a multi-line comment on a new discussion + uses: actions/github-script@v6 + with: + script: | + const { owner, repo } = context.repo; + const discussion_id = context.payload.discussion.node_id; + + const mutation = ` + mutation($discussionId: ID!, $body: String!) { + addDiscussionComment(input: {discussionId: $discussionId, body: $body}) { + comment { + id + } + } + } + `; + + const body = ` + Thank you for starting a new discussion! + + We appreciate your input and will review it soon. + + > [!WARNING] + > A friendly reminder that this is a public forum. Please be cautious when clicking links, downloading files, or running scripts posted by others. + > + > - Always verify the credibility of links and code. + > - Avoid running scripts or installing files from untrusted sources. + > - If you're unsure, ask for clarification before proceeding. + + Stay safe and happy SLEAPing! + + Best regards, + The Team + `; + + await github.graphql(mutation, { + discussionId: discussion_id, + body: body.trim() // Removes trailing/leading whitespace + }); From 308f40fb2f52e256a86d29f5c3dedacdf3a65a05 Mon Sep 17 00:00:00 2001 From: Liezl Maree <38435167+roomrys@users.noreply.github.com> Date: Fri, 6 Sep 2024 10:41:53 -0700 Subject: [PATCH 3/6] Add comment on issue workflow (#1946) --- .github/workflows/comment-template.yml | 71 ++++++++++++++++++++++++++ .github/workflows/comment.yml | 62 +++++++--------------- 2 files changed, 89 insertions(+), 44 deletions(-) create mode 100644 .github/workflows/comment-template.yml diff --git a/.github/workflows/comment-template.yml b/.github/workflows/comment-template.yml new file mode 100644 index 000000000..3bef84531 --- /dev/null +++ b/.github/workflows/comment-template.yml @@ -0,0 +1,71 @@ +name: Reusable Comment Workflow + +on: + workflow_call: + inputs: + subject_id: + required: true + type: string + body_prefix: + required: true + type: string + comment_type: + required: true + type: string + +jobs: + comment: + runs-on: ubuntu-latest + steps: + - name: Post a comment + uses: actions/github-script@v6 + with: + script: | + const { owner, repo } = context.repo; + const subject_id = '${{ inputs.subject_id }}'; + const comment_type = '${{ inputs.comment_type }}'; + const baseBody = ` + We appreciate your input and will review it soon. + + > [!WARNING] + > A friendly reminder that this is a public forum. Please be cautious when clicking links, downloading files, or running scripts posted by others. + > + > - Always verify the credibility of links and code. + > - Avoid running scripts or installing files from untrusted sources. + > - If you're unsure, ask for clarification before proceeding. + + Stay safe and happy SLEAPing! + + Best regards, + The Team + `; + const body = `${{ inputs.body_prefix }}\n\n${baseBody}`; + + const mutation = comment_type === 'discussion' + ? ` + mutation($discussionId: ID!, $body: String!) { + addDiscussionComment(input: {discussionId: $discussionId, body: $body}) { + comment { + id + } + } + } + ` + : ` + mutation($issueId: ID!, $body: String!) { + addComment(input: {subjectId: $issueId, body: $body}) { + commentEdge { + node { + id + body + } + } + } + } + `; + + const variables = comment_type === 'discussion' + ? { discussionId: subject_id, body: body.trim() } + : { issueId: subject_id, body: body.trim() }; + + await github.graphql(mutation, variables); diff --git a/.github/workflows/comment.yml b/.github/workflows/comment.yml index 39423ad54..a24df018f 100644 --- a/.github/workflows/comment.yml +++ b/.github/workflows/comment.yml @@ -1,50 +1,24 @@ -name: Comment on New Discussions +name: Comment on New Discussions and Issues on: discussion: types: [created] + issues: + types: [opened] jobs: - comment: - runs-on: ubuntu-latest - - steps: - - name: Post a multi-line comment on a new discussion - uses: actions/github-script@v6 - with: - script: | - const { owner, repo } = context.repo; - const discussion_id = context.payload.discussion.node_id; - - const mutation = ` - mutation($discussionId: ID!, $body: String!) { - addDiscussionComment(input: {discussionId: $discussionId, body: $body}) { - comment { - id - } - } - } - `; - - const body = ` - Thank you for starting a new discussion! - - We appreciate your input and will review it soon. - - > [!WARNING] - > A friendly reminder that this is a public forum. Please be cautious when clicking links, downloading files, or running scripts posted by others. - > - > - Always verify the credibility of links and code. - > - Avoid running scripts or installing files from untrusted sources. - > - If you're unsure, ask for clarification before proceeding. - - Stay safe and happy SLEAPing! - - Best regards, - The Team - `; - - await github.graphql(mutation, { - discussionId: discussion_id, - body: body.trim() // Removes trailing/leading whitespace - }); + comment_on_discussion: + if: github.event_name == 'discussion' + uses: ./.github/workflows/comment-template.yml + with: + subject_id: ${{ github.event.discussion.node_id }} + body_prefix: "Thank you for starting a new discussion!" + comment_type: "discussion" + + comment_on_issue: + if: github.event_name == 'issues' + uses: ./.github/workflows/comment-template.yml + with: + subject_id: ${{ github.event.issue.node_id }} + body_prefix: "Thank you for opening a new issue!" + comment_type: "issue" From 84e751ef23fd994eada3c2cf3754e35e10d5c022 Mon Sep 17 00:00:00 2001 From: Liezl Maree <38435167+roomrys@users.noreply.github.com> Date: Fri, 6 Sep 2024 10:43:47 -0700 Subject: [PATCH 4/6] Add workflow to test conda packages (#1935) --- .github/workflows/build_conda_ci.yml | 179 ++++++++++++++++++ .../{build_ci.yml => build_pypi_ci.yml} | 28 +-- 2 files changed, 193 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/build_conda_ci.yml rename .github/workflows/{build_ci.yml => build_pypi_ci.yml} (91%) diff --git a/.github/workflows/build_conda_ci.yml b/.github/workflows/build_conda_ci.yml new file mode 100644 index 000000000..0d5980730 --- /dev/null +++ b/.github/workflows/build_conda_ci.yml @@ -0,0 +1,179 @@ +# Run tests using built conda packages. +name: Build Conda CI (no upload) + +# Run when changes to pip wheel +on: + push: + paths: + - ".conda/meta.yaml" + - ".conda_mac/meta.yaml" + - "setup.py" + - "requirements.txt" + - "dev_requirements.txt" + - "environment_build.yml" + - ".github/workflows/build_conda_ci.yml" + +# If RUN_BUILD_JOB is set to true, then RUN_ID will be overwritten to the current run id +env: + RUN_BUILD_JOB: true + RUN_ID: 10713717594 # Only used if RUN_BUILD_JOB is false (to dowload build artifact) + +jobs: + build: + name: Build package from push (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: ["windows-2022", "ubuntu-22.04", "macos-14"] + # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrixinclude + include: + # Use these variables as defaults + - condarc: .conda/condarc.yaml + - conda-folder: .conda + - pyver: "3.10" + - build-prefix: win + - os: "ubuntu-22.04" + build-prefix: linux + # Use special condarc if macos + - os: "macos-14" + condarc: .conda_mac/condarc.yaml + conda-folder: .conda_mac + build-prefix: osx + + steps: + # Setup + - name: Checkout + if: env.RUN_BUILD_JOB == 'true' + uses: actions/checkout@v4 + + - name: Setup Miniconda + if: env.RUN_BUILD_JOB == 'true' + uses: conda-incubator/setup-miniconda@v3.0.4 + with: + miniforge-version: latest + condarc-file: ${{ matrix.condarc }} + python-version: ${{ matrix.pyver }} + environment-file: environment_build.yml + activate-environment: sleap_ci + conda-solver: "libmamba" + + - name: Print build environment info + if: env.RUN_BUILD_JOB == 'true' + shell: bash -l {0} + run: | + which python + conda list + pip freeze + + # Build conda package + - name: Build conda package + if: env.RUN_BUILD_JOB == 'true' + shell: bash -l {0} + run: | + conda build ${{ matrix.conda-folder }} --output-folder build + + # Upload artifact "tests" can use it + - name: Upload conda package artifact + if: env.RUN_BUILD_JOB == 'true' + uses: actions/upload-artifact@v4 + with: + name: sleap-build-${{ matrix.build-prefix }} + path: build # Upload entire build directory + retention-days: 1 + overwrite: true + + tests: + name: Run tests using package (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + needs: build # Ensure the build job has completed before starting this job. + strategy: + fail-fast: false + matrix: + os: ["windows-2022", "ubuntu-22.04", "macos-14"] + # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrixinclude + include: + # Default values + - build-prefix: win + - build-suffix: 64 + - test_args: pytest --durations=-1 tests/ + - condarc: .conda/condarc.yaml + - pyver: "3.10" + - conda-channels: -c conda-forge -c nvidia -c anaconda + # Ubuntu specific values + - os: ubuntu-22.04 + build-prefix: linux + # Otherwise core dumped in github actions + test_args: | + sudo apt install xvfb libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 + sudo Xvfb :1 -screen 0 1024x768x24 > $GITHUB_ENV + + # https://github.com/actions/download-artifact?tab=readme-ov-file#usage + - name: Download conda package artifact + uses: actions/download-artifact@v4 + id: download + with: + name: sleap-build-${{ matrix.build-prefix }} + path: build + run-id: ${{ env.RUN_ID }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: List items in current directory + run: | + ls . + ls -R build + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v3.0.4 + with: + miniforge-version: latest + condarc-file: ${{ matrix.condarc }} + python-version: ${{ matrix.pyver }} + conda-solver: "libmamba" + + - name: Create conda environment + shell: bash -l {0} + run: conda create sleap -y -n sleap_ci -c ./build ${{ matrix.conda-channels }} + + - name: Install packages for testing + shell: bash -l {0} + run: | + conda activate sleap_ci + pip install -r "dev_requirements.txt" + + # Note: "conda activate" does not persist across steps + - name: Print environment info + shell: bash -l {0} + run: | + conda activate sleap_ci + conda info + conda list + pip freeze + + - name: Test package + shell: bash -l {0} + run: | + conda activate sleap_ci + ${{ matrix.test_args}} diff --git a/.github/workflows/build_ci.yml b/.github/workflows/build_pypi_ci.yml similarity index 91% rename from .github/workflows/build_ci.yml rename to .github/workflows/build_pypi_ci.yml index ac18022d6..c22cc5a69 100644 --- a/.github/workflows/build_ci.yml +++ b/.github/workflows/build_pypi_ci.yml @@ -1,17 +1,17 @@ # Run tests using built wheels. -name: Build CI (no upload) +name: Build PyPI CI (no upload) # Run when changes to pip wheel on: push: paths: - - 'setup.py' - - 'requirements.txt' - - 'dev_requirements.txt' - - 'jupyter_requirements.txt' - - 'pypi_requirements.txt' - - 'environment_build.yml' - - '.github/workflows/build_ci.yml' + - "setup.py" + - "requirements.txt" + - "dev_requirements.txt" + - "jupyter_requirements.txt" + - "pypi_requirements.txt" + - "environment_build.yml" + - ".github/workflows/build_pypi_ci.yml" jobs: build: @@ -54,7 +54,7 @@ jobs: shell: bash -l {0} run: | python setup.py bdist_wheel - + # Upload artifact "tests" can use it - name: Upload wheel artifact uses: actions/upload-artifact@v4 @@ -66,7 +66,7 @@ jobs: tests: name: Run tests using wheel (${{ matrix.os }}) runs-on: ${{ matrix.os }} - needs: build # Ensure the build job has completed before starting this job. + needs: build # Ensure the build job has completed before starting this job. strategy: fail-fast: false matrix: @@ -103,12 +103,12 @@ jobs: steps: - name: Checkout repo uses: actions/checkout@v4 - + - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ matrix.pyver }} - + # Download wheel - name: Download wheel artifact uses: actions/download-artifact@v4 @@ -144,8 +144,8 @@ jobs: run: | which python pip freeze - + # Install and test the wheel - name: Test the built wheel run: | - ${{ matrix.test_args}} \ No newline at end of file + ${{ matrix.test_args}} From 7299fd77096f9290b4f722f8c4ef473d498bf1cc Mon Sep 17 00:00:00 2001 From: Liezl Maree <38435167+roomrys@users.noreply.github.com> Date: Fri, 6 Sep 2024 10:44:55 -0700 Subject: [PATCH 5/6] Add missing imageio-ffmpeg to meta.ymls (#1943) --- .conda/meta.yaml | 2 ++ .conda_mac/meta.yaml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.conda/meta.yaml b/.conda/meta.yaml index 55a08c091..30b0fc158 100644 --- a/.conda/meta.yaml +++ b/.conda/meta.yaml @@ -33,6 +33,7 @@ requirements: - conda-forge::attrs ==21.4.0 - conda-forge::cattrs ==1.1.1 - conda-forge::h5py ==3.7.0 + - conda-forge::imageio-ffmpeg # Required for imageio to read/write videos with ffmpeg - conda-forge::jsmin - conda-forge::jsonpickle ==1.2 - conda-forge::networkx @@ -60,6 +61,7 @@ requirements: - conda-forge::python ==3.7.12 # Run into _MAX_WINDOWS_WORKERS not found if < - conda-forge::attrs ==21.4.0 - conda-forge::cattrs ==1.1.1 + - conda-forge::imageio-ffmpeg # Required for imageio to read/write videos with ffmpeg - conda-forge::cudatoolkit ==11.3.1 - conda-forge::cudnn=8.2.1 - nvidia::cuda-nvcc=11.3 diff --git a/.conda_mac/meta.yaml b/.conda_mac/meta.yaml index ccfc399c0..403558f7c 100644 --- a/.conda_mac/meta.yaml +++ b/.conda_mac/meta.yaml @@ -34,6 +34,7 @@ requirements: - conda-forge::attrs >=21.2.0 - conda-forge::cattrs ==1.1.1 - conda-forge::h5py + - conda-forge::imageio-ffmpeg # Required for imageio to read/write videos with ffmpeg - conda-forge::jsmin - conda-forge::jsonpickle ==1.2 - conda-forge::keras <2.10.0,>=2.9.0rc0 # Required by tensorflow-macos @@ -63,6 +64,7 @@ requirements: - conda-forge::attrs >=21.2.0 - conda-forge::cattrs ==1.1.1 - conda-forge::h5py + - conda-forge::imageio-ffmpeg # Required for imageio to read/write videos with ffmpeg - conda-forge::jsmin - conda-forge::jsonpickle ==1.2 - conda-forge::keras <2.10.0,>=2.9.0rc0 # Required by tensorflow-macos From 91d6c96dd77bc092d7835046245fb787b444523d Mon Sep 17 00:00:00 2001 From: Liezl Maree <38435167+roomrys@users.noreply.github.com> Date: Fri, 6 Sep 2024 11:29:14 -0700 Subject: [PATCH 6/6] 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 Co-authored-by: Talmo Pereira --- .conda/README.md | 4 +- .github/workflows/website.yml | 8 +- dev_requirements.txt | 7 +- docs/_static/css/tabs.css | 91 ++++++++ docs/conf.py | 11 + docs/installation.md | 423 +++++++++++++++++----------------- 6 files changed, 322 insertions(+), 222 deletions(-) create mode 100644 docs/_static/css/tabs.css 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/.github/workflows/website.yml b/.github/workflows/website.yml index 544a462b5..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 - - 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 \ No newline at end of file + destination_dir: develop diff --git a/dev_requirements.txt b/dev_requirements.txt index f7bb23643..709fb48fd 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>=0.16.0 # sphinx>=5.0 needs myst-nb>=0.16.0 +myst-parser linkify-it-py sphinx-autobuild black==21.6b0 diff --git a/docs/_static/css/tabs.css b/docs/_static/css/tabs.css new file mode 100644 index 000000000..95765dff6 --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 6cd9593ef..a429c7928 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", ] @@ -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 diff --git a/docs/installation.md b/docs/installation.md index c0ab66580..4799a0893 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,10 +1,21 @@ # 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. For quick install using conda, see below: -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. +````{tabs} + ```{group-tab} Windows and Linux + ```bash + conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a2 + ``` + ``` + ```{group-tab} Mac OS + ```bash + conda create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a2 + ``` + ``` +```` -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 --- @@ -12,66 +23,30 @@ 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_. - -```` - -(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)" - ``` - +`````{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_. + ``` ```` +````` - Then, close and re-open the terminal for it to take effect. +## Package Manager -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. +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, 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 @@ -80,195 +55,221 @@ 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. ``` ```` -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. - -``` +If you don't have a `conda` package manager installation, here are some quick install options: -**On Macs (pre-M1)**, you can run the installer using this terminal command: +### Miniforge (recommended) -```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 -``` +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. -**On Macs (Apple Silicon)**, use this terminal command: -```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" -``` +````{tabs} + ```{group-tab} Windows + Open a new PowerShell terminal (does not need to be admin) and enter: -## 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`. - -(condapackage)= - -### `conda` package - -**Windows** and **Linux** - -```bash -mamba create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a2 -``` - -**Mac OS X** and **Apple Silicon** - -```bash -mamba create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a2 -``` - -**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 - -1. First, ensure git is installed: - - ```bash - git --version + ```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: - 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 + ```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: -3. Finally, install from the environment file (differs based on OS and GPU): - - **Windows** and **Linux** - - ```bash - mamba env create -f environment.yml -n sleap + ```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: - If you do not have a NVIDIA GPU, then you should use the no CUDA environment file: - - ```bash - mamba env create -f environment_no_cuda.yml -n sleap - ``` - - **Mac OS X** and **Apple Silicon** - - ```bash - mamba env create -f environment_mac.yml -n sleap + ```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" + ``` ``` +```` - This is the **recommended method for development**. - -```{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`). -``` - -(pippackage)= - -### `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. +### Miniconda -1. Otherwise, create a new conda environment where we will `pip install sleap`: +This is a minimal installer for conda that includes the `conda` package manager and is maintained by the [Anaconda](https://www.anaconda.com) company. - either without GPU support: +````{tabs} + ```{group-tab} Windows + Open a new PowerShell terminal (does not need to be admin) and enter: - ```bash - mamba create --name sleap pip python=3.7.12 + ```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: - or with GPU support: - - ```bash - mamba create --name sleap pip python=3.7.12 cudatoolkit=11.3 cudnn=8.2 + ```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: -2. Then activate the environment to isolate the `pip install` from other environments on your computer: - - ```bash - mamba activate sleap + ```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: - ```{warning} - Refrain from installing anything into the `base` environment. Always create a new environment to install new packages. + ```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" + ``` ``` +```` -3. Finally, we can perform the `pip install`: - - ```bash - pip install sleap[pypi]==1.4.1a2 - ``` +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. - 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. - ``` +(installation-methods)= +## Installation methods - ```{note} - - Requires Python 3.7 - - To enable GPU support, make sure that you have **CUDA Toolkit v11.3** and **cuDNN v8.2** installed. - ``` +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`. - ```{warning} - This will uninstall existing libraries and potentially install conflicting ones. +````{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.1a2 + ``` + ```{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.1a2 + ``` + ```{note} + This will also work in CPU mode if you don't have a GPU on your machine. + ``` + ``` + ```` - We strongly recommend that you **only use this method if you know what you're doing**! ``` + ```{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.1a2 + ``` + ```{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. + - **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 conda 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 conda 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 + Not supported. + ``` + ```` + ``` +```` ## Testing that things are working -If you installed using `mamba`, first activate the `sleap` environment by opening a terminal and typing: +If you installed using `conda`, first activate the `sleap` environment by opening a terminal and typing: ```bash -mamba activate sleap +conda activate sleap ``` ````{hint} -Not sure what `mamba` environments you already installed? You can get a list of the environments on your system with: +Not sure what `conda` environments you already installed? You can get a list of the environments on your system with: ``` -mamba env list +conda env list ``` ```` @@ -301,7 +302,7 @@ python -c "import sleap; sleap.versions()" ### GPU support -Assuming you installed using either of the `mamba`-based methods on Windows or Linux, SLEAP should automatically have GPU support enabled. +Assuming you installed using either of the `conda`-based methods on Windows or Linux, SLEAP should automatically have GPU support enabled. To check, verify that SLEAP can detect the GPUs on your system: @@ -362,7 +363,7 @@ file: No such file or directory then activate the environment: ```bash -mamba activate sleap +conda activate sleap ``` and run the commands: @@ -391,13 +392,13 @@ We **strongly recommend** installing SLEAP in a fresh environment when updating. To uninstall an existing environment named `sleap`: ```bash -mamba env remove -n sleap +conda env remove -n sleap ``` ````{hint} -Not sure what `mamba` environments you already installed? You can get a list of the environments on your system with: +Not sure what `conda` environments you already installed? You can get a list of the environments on your system with: ```bash -mamba env list +conda env list ``` ```` @@ -413,10 +414,10 @@ If you get any errors or the GUI fails to launch, try running the diagnostics to sleap-diagnostic ``` -If you were not able to get SLEAP installed, activate the mamba environment it is in and generate a list of the package versions installed: +If you were not able to get SLEAP installed, activate the conda environment it is in and generate a list of the package versions installed: ```bash -mamba list +conda list ``` Then, [open a new Issue](https://github.com/talmolab/sleap/issues) providing the versions from either command above, as well as any errors you saw in the console during the installation. Or [start a discussion](https://github.com/talmolab/sleap/discussions) to get help from the community.