Update docs for 1.2.0 (talmolab#674)

* Update installation instructions
* Update theme and fix content formatting
* Convert some guides to md, add notice, readme tweak
* Bump version number
* Disable manual build temporarily

.conda/meta.yaml

@@ -16,7 +16,7 @@ about:
   summary: {{ data.get('description') }}
 
 build:
-  number: 4
+  number: 0
 
 source:
   path: ../

.github/workflows/build_manual.yml

@@ -2,10 +2,10 @@
 # To trigger a build, bump the build number in .conda/meta.yaml.
 name: Build (manual)
 
-on:
-  push:
-    paths:
-      - '.conda/meta.yaml'
+# on:
+#   push:
+#     paths:
+#       - '.conda/meta.yaml'
 
   # Uncomment the following lines to trigger a build if the release build failed
   # push:

.github/workflows/website.yml

@@ -8,6 +8,7 @@ on:
       # 'main' triggers updates to 'sleap.ai', 'develop' to 'sleap.ai/develop'
       - main
       - develop
+      - talmo/update-docs-pre-migration
     paths:
       - 'docs/**'
       - 'README.rst'
@@ -32,7 +33,7 @@ jobs:
         # https://github.com/conda-incubator/setup-miniconda
         uses: conda-incubator/[email protected]
         with:
-          python-version: 3.6
+          python-version: 3.7
           use-only-tar-bz2: true # IMPORTANT: This needs to be set for caching to work properly!
           environment-file: environment_build.yml
           activate-environment: sleap

README.rst

@@ -21,85 +21,138 @@
    :alt: Downloads
 
 .. |Stable version| image:: https://img.shields.io/github/v/release/murthylab/sleap?label=stable
-   :target: https://GitHub.com/murthylab/sleap/releases/
+   :target: https://github.com/murthylab/sleap/releases/
    :alt: Stable version
 
 .. |Latest version| image:: https://img.shields.io/github/v/release/murthylab/sleap?include_prereleases&label=latest
-   :target: https://GitHub.com/murthylab/sleap/releases/
+   :target: https://github.com/murthylab/sleap/releases/
    :alt: Latest version
 
 
 .. start-inclusion-marker-do-not-remove
 
 
-**SLEAP** - Social LEAP Estimates Animal Poses
-==============================================
+Social LEAP Estimates Animal Poses (SLEAP)
+==========================================
 
 .. image:: https://sleap.ai/docs/_static/sleap_movie.gif
     :width: 600px
 
-**SLEAP** is an open source deep-learning based framework for estimating positions of animal body parts. It supports *multi-animal pose estimation* and *tracking*, and includes an advanced labeling/training GUI for active learning and proofreading.
-
-SLEAP is written in Python and uses TensorFlow 2 for machine learning and Qt/PySide2 for graphical user interface. SLEAP is the successor to `LEAP <https://github.com/talmo/leap>`_ (`Pereira et al., Nature Methods, 2019 <https://www.nature.com/articles/s41592-018-0234-5>`_).
+**SLEAP** is an open source deep-learning based framework for multi-animal pose tracking. It can be used to track any type or number of animals and includes an advanced labeling/training GUI for active learning and proofreading.
 
 
 Features
-------------
-
+--------
+* Easy, one-line installation with support for all OSes
 * Purpose-built GUI and human-in-the-loop workflow for rapidly labeling large datasets
-* Multi-animal pose estimation with *top-down* and *bottom-up* training strategies
+* Single- and multi-animal pose estimation with *top-down* and *bottom-up* training strategies
 * State-of-the-art pretrained and customizable neural network architectures that deliver *accurate predictions* with *very few* labels
 * Fast training: 15 to 60 mins on a single GPU for a typical dataset
-* Fast inference: 400+ FPS for batch, <10ms latency for realtime
+* Fast inference: up to 600+ FPS for batch, <10ms latency for realtime
 * Support for remote training/inference workflow (for using SLEAP without GPUs)
 * Flexible developer API for building integrated apps and customization
 
 
-Getting started
-----------------
+Get some SLEAP
+--------------
+SLEAP is installed as a Python package. We strongly recommend using `Miniconda <https://https://docs.conda.io/en/latest/miniconda.html>`_ to install SLEAP in its own environment.
+
+You can find the latest version of SLEAP in the `Releases <https://github.com/murthylab/sleap/releases>`_ page.
 
-To get started with SLEAP, head over to the `Documentation <https://sleap.ai>`_ where you'll find tutorials, guides and example notebooks.
+Quick install
+^^^^^^^^^^^^^
+`conda` **(Windows/Linux/GPU)**:
 
-To learn more about the technical side of SLEAP and multi-animal pose tracking, check out our `preprint on bioRxiv <https://doi.org/10.1101/2020.08.31.276246>`_ or watch the `tutorial on SLEAP <https://cbmm.mit.edu/video/decoding-animal-behavior-through-pose-tracking>`_. For a more general introduction to the field of quantitative animal behavior, check out our `review in Nature Neuroscience <https://rdcu.be/caH3H>`_.
+.. code-block:: bash
 
-You can find the latest version of SLEAP in the `Releases <https://github.com/murthylab/sleap/releases>`_ page.
+    conda create -y -n sleap -c sleap -c nvidia -c conda-forge sleap
+
+
+`pip` **(any OS)**:
+
+.. code-block:: bash
+
+    pip install sleap
+
+
+See the docs for `full installation instructions <https://sleap.ai/installation.html>`_.
+
+Learn to SLEAP
+--------------
+- **Learn step-by-step**: `Tutorial <https://sleap.ai/tutorials/tutorial.html>`_
+- **Learn more advanced usage**: `Guides <https://sleap.ai/guides/>`_ and `Notebooks <https://sleap.ai/notebooks/>`_
+- **Learn by watching**: `MIT CBMM Tutorial <https://cbmm.mit.edu/video/decoding-animal-behavior-through-pose-tracking>`_
+- **Learn by reading**: `Paper (Pereira et al., bioRxiv, 2020) <https://doi.org/10.1101/2020.08.31.276246>`_ and `Review on behavioral quantification (Pereira et al., Nature Neuroscience, 2020) <https://rdcu.be/caH3H>`_
 
 
 References
 -----------
-If you use **SLEAP** in your research, please cite:
+SLEAP is the successor to the single-animal pose estimation software `LEAP <https://github.com/talmo/leap>`_ (`Pereira et al., Nature Methods, 2019 <https://www.nature.com/articles/s41592-018-0234-5>`_).
 
-    Talmo D. Pereira, Nathaniel Tabris, Junyu Li, Shruthi Ravindranath, Eleni S. Papadoyannis, Z. Yan Wang, David M. Turner, et al. 2020. "SLEAP: Multi-Animal Pose Tracking." *bioRxiv*. https://doi.org/10.1101/2020.08.31.276246.
+If you use SLEAP in your research, please cite:
+
+    Pereira, Talmo D., Nathaniel Tabris, Junyu Li, Shruthi Ravindranath, Eleni S. Papadoyannis, Z. Yan Wang, David M. Turner, et al. 2020. "SLEAP: Multi-Animal Pose Tracking." *bioRxiv*. https://doi.org/10.1101/2020.08.31.276246.
+
+
+**BibTeX:**
+
+.. code-block:: tex
+
+   @ARTICLE{Pereira2020-tt,
+   title    = "{SLEAP}: Multi-animal pose tracking",
+   author   = "Pereira, Talmo D and Tabris, Nathaniel and Li, Junyu and
+               Ravindranath, Shruthi and Papadoyannis, Eleni S and Yan Wang, Z
+               and Turner, David M and McKenzie-Smith, Grace and Kocher, Sarah D
+               and Falkner, Annegret Lea and Shaevitz, Joshua W and Murthy, Mala",
+   journal  = "bioRxiv",
+   pages    = "2020.08.31.276246",
+   month    =  sep,
+   year     =  2020,
+   language = "en"
+   }
 
-License
--------
-SLEAP is released under a `Clear BSD License <https://raw.githubusercontent.com/murthylab/sleap/main/LICENSE>`_ and is intended for research/academic use only. For commercial use, please contact: Laurie Tzodikov (Assistant Director, Office of Technology Licensing), Princeton University, 609-258-7256.
 
 Contact
 -------
 
-Follow `@MurthyLab <https://twitter.com/MurthyLab>`_ on Twitter for news and updates!
+Follow `@talmop <https://twitter.com/talmop>`_ on Twitter for news and updates!
 
-**Technical issue with the software?** Check the `Help page <https://sleap.ai/help.html>`_ first, then `open an issue on GitHub. <https://github.com/murthylab/sleap/issues>`_
+**Technical issue with the software?**
 
-**Press inquiries? Interested in using SLEAP in a commercial application?** Reach out at `[email protected]`_.
+1. Check the `Help page <https://sleap.ai/help.html>`_.
+2. Search the `issues on GitHub <https://github.com/murthylab/sleap/issues>`_ or open a new one.
 
-.. _[email protected]: [email protected]
 
+**General inquiries?**
+Reach out to `[email protected]`.
 
 .. _Contributors:
 
 Contributors
 ------------
 
-* **Talmo Pereira**, Princeton Neuroscience Institute, Princeton University
+* **Talmo Pereira**, Salk Institute for Biological Studies
+* **Liezl Maree**, Salk Institute for Biological Studies
 * **Arie Matsliah**, Princeton Neuroscience Institute, Princeton University
 * **Nat Tabris**, Princeton Neuroscience Institute, Princeton University
 * **David Turner**, Research Computing and Princeton Neuroscience Institute, Princeton University
 * **Joshua Shaevitz**, Physics and Lewis-Sigler Institute, Princeton University
 * **Mala Murthy**, Princeton Neuroscience Institute, Princeton University
 
-SLEAP is developed in the `Murthy <https://murthylab.princeton.edu>`_ and `Shaevitz <https://shaevitzlab.princeton.edu>`_ labs at the `Princeton Neuroscience Institute <https://pni.princeton.edu>`_ at Princeton University. This work was made possible through our funding sources, including: NIH BRAIN Initiative R01 NS104899 and Princeton Innovation Accelerator Fund.
+SLEAP was created in the `Murthy <https://murthylab.princeton.edu>`_ and `Shaevitz <https://shaevitzlab.princeton.edu>`_ labs at the `Princeton Neuroscience Institute <https://pni.princeton.edu>`_ at Princeton University.
+
+SLEAP is currently being developed and maintained in the `Talmo Lab <https://talmolab.org>`_ at the `Salk Institute for Biological Studies <https://salk.edu>`_, in collaboration with the Murthy and Shaevitz labs at Princeton University.
+
+This work was made possible through our funding sources, including:
+
+* NIH BRAIN Initiative R01 NS104899
+* Princeton Innovation Accelerator Fund
+
+
+License
+-------
+SLEAP is released under a `Clear BSD License <https://raw.githubusercontent.com/murthylab/sleap/main/LICENSE>`_ and is intended for research/academic use only. For commercial use, please contact: Laurie Tzodikov (Assistant Director, Office of Technology Licensing), Princeton University, 609-258-7256.
+
 
 .. end-inclusion-marker-do-not-remove
 

dev_requirements.txt

@@ -4,8 +4,11 @@ pytest-cov
 pytest-xvfb
 ipython
 sphinx
-furo
+# furo
+sphinx-book-theme
 sphinx-copybutton
+myst-parser
+linkify-it-py
 myst-nb
 sphinx-autobuild
 black==21.6b0

docs/conf.py

@@ -23,23 +23,23 @@
 # -- Project information -----------------------------------------------------
 
 project = "SLEAP"
-author = "Talmo D. Pereira, Arie Matsliah, Nat Tabris, David M. Turner"
-copyright = "2019–2021, Murthy Lab @ Princeton University"
+author = "Talmo D. Pereira"
+copyright = "2019–2022, Talmo Lab"
 
 # The short X.Y version
-version = "1.1.5"
+version = "1.2.0"
 
 # Get the sleap version
 # with open("../sleap/version.py") as f:
 #     version_file = f.read()
 #     version = re.search("\d.+(?=['\"])", version_file).group(0)
 
 # Release should be the full branch name
-release = "v1.1.5"
+release = "v1.2.0"
 
 html_title = f"SLEAP ({release})"
 html_short_title = "SLEAP"
-html_favicon = '_static/favicon.ico'
+html_favicon = "_static/favicon.ico"
 html_baseurl = "/develop/"
 
 # -- General configuration ---------------------------------------------------
@@ -58,6 +58,7 @@
     "sphinx.ext.linkcode",
     "sphinx.ext.napoleon",
     "sphinx_copybutton",
+    # https://myst-nb.readthedocs.io/en/latest/
     "myst_nb",
 ]
 
@@ -103,6 +104,7 @@ def linkcode_resolve(domain, info):
         print(info)
         raise
 
+
 autosummary_generate = True
 
 # Enable automatic role inference as a Python object for autodoc.
@@ -118,17 +120,44 @@ def linkcode_resolve(domain, info):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "furo"
+# html_theme = "furo"
+html_theme = "sphinx_book_theme"
 
 # Customization options.
 # https://pradyunsg.me/furo/customisation/
 html_theme_options = {
     # Set this to add a site-wide banner:
     # "announcement": "<em>Important</em> announcement!",
-    "light_logo": "logo.png",
-    "dark_logo": "logo.png",
+    # "light_logo": "logo.png",
+    # "dark_logo": "logo.png",
+    # https://sphinx-book-theme.readthedocs.io/en/stable/customize/index.html#theme-options
+    "repository_url": "https://github.com/murthylab/sleap",
+    "use_repository_button": True,
+    "use_download_button": False,
+    "extra_navbar": "",
 }
 
+myst_number_code_blocks = ["python"]
+
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    # "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    # "strikethrough",
+    "substitution",
+    "tasklist",
+]
+
+html_logo = "_static/logo.png"
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -178,5 +207,5 @@ def linkcode_resolve(domain, info):
     shutil.rmtree(_docs_static_path)
 shutil.copytree("_static", _docs_static_path)
 
-
-jupyter_execute_notebooks = "off"
+# https://myst-nb.readthedocs.io/en/latest/use/config-reference.html
+jupyter_execute_notebooks = "off"

docs/guides/cli.rst

@@ -296,7 +296,7 @@ Debugging
 ``sleap-diagnostic``
 ++++++++++++++++++++
 
-There's also a script to output diagnostic information which may help us if you need to contact us about problems installing or running SLEAP. If you were able to install the SLEAP Python package, you can run this script with :code:`sleap-diagnostic`. Otherwise, you can download `diagnostic.py <https://raw.githubusercontent.com/murthylab/sleap/main/sleap/diagnostic.py?token=ALBFDHR54MUCZQEU4PKGK4S6PX2KY>`_ and run :code:`python diagnostic.py`.
+There's also a script to output diagnostic information which may help us if you need to contact us about problems installing or running SLEAP. If you were able to install the SLEAP Python package, you can run this script with :code:`sleap-diagnostic`. Otherwise, you can download `diagnostic.py <https://raw.githubusercontent.com/murthylab/sleap/main/sleap/diagnostic.py>`_ and run :code:`python diagnostic.py`.
 
 
 .. code-block:: none

docs/guides/custom-training.rst → docs/guides/custom-training.md

@@ -1,29 +1,30 @@
-.. _custom_training:
+(custom-training)=
 
-Creating a custom training profile
------------------------------------
+# Creating a custom training profile
 
 *Case: You've created a project with training data on one computer, and you want to use a different computer for training models with custom hyperparameters.*
 
 Hyperparameters include the model architecture, learning rate, and data augmentation settings. While model **parameters** are learned from your data during training, **hyperparameters** are not learned from your data—they have to be set before training since they control the training process.
 
-This guide will explain how to create a custom training profile but doesn't cover how to decide what the hyperpameters should be. For more information about the hyperparameters, see our guide to :ref:`choosing_models`.
+This guide will explain how to create a custom training profile but doesn't cover how to decide what the hyperpameters should be. For more information about the hyperparameters, see our guide to {ref}`choosing_models`.
 
-Training profiles are JSON files. The JSON format is fairly easy to read (and edit) with a text-editor and you can use the default "baseline" profiles as a starting point for creating your own training profiles. For example, take a look at the `baseline bottom-up profile <https://github.com/murthylab/sleap/blob/main/sleap/training_profiles/baseline.bottomup.json>`_ or our `other baseline profiles <https://github.com/murthylab/sleap/blob/main/sleap/training_profiles>`_.
+Training profiles are JSON files. The JSON format is fairly easy to read (and edit) with a text-editor and you can use the default "baseline" profiles as a starting point for creating your own training profiles. For example, take a look at the [baseline bottom-up profile](https://github.com/murthylab/sleap/blob/main/sleap/training_profiles/baseline_medium_rf.bottomup.json) or our [other baseline profiles](https://github.com/murthylab/sleap/blob/main/sleap/training_profiles).
 
 But if this sounds intimidating, you don't have to edit the JSON file by hand! You can use the same GUI that's used for training on a local machine to export custom training profiles.
 
 If it isn't open already, run SLEAP and open the SLEAP project with your training dataset. Then select the "**Run Training...**" command in the "**Predict**" menu. You'll see the training GUI which lets you configure the pipeline type and the hyperparameters for each model:
 
-.. image:: ../_static/training-dialog.jpg
+```{image} ../_static/training-dialog.jpg
+```
 
 First pick the desired pipeline (i.e., top-down, bottom-up, or single animal). For each model in the pipeline, you'll then see a "**Model Configuration**" tab—in the image above with the top-down pipeline, there's one tab for configuring the centroid model and one for the centered instance model. Other pipelines will only have one model to configure.
 
 You can click on each model configuration tab to configure the hyperpameters for training that model:
 
-.. image:: ../_static/training-model-dialog.jpg
+```{image} ../_static/training-model-dialog.jpg
+```
 
-For advice about what you might want to customize with this dialog, see our guide to :ref:`choosing_models`.
+For advice about what you might want to customize with this dialog, see our guide to {ref}`choosing_models`.
 
 Once you've configured each of your models, click the "**Save configuration files...**" button at the bottom of the dialog. You'll be prompted for where to save the files. It's a good idea to create a new folder which will contain the files since there will be multiple files exported.
 
@@ -37,9 +38,12 @@ Wherever you selected to save your files, you'll now have a custom training prof
 
 If you're running training on a remote machine (including Colab), export your training job package into the remote machine. Then call:
 
-::
+```
+sleap-train path/to/custom/profile.json path/to/dataset.pkg.slp
+```
 
-    sleap-train path/to/custom/profile.json path/to/dataset.pkg.slp
-
-for each model you want to train (where `path/to/custom/profile.json` should be replaced with the path to your custom training profile and `path/to/dataset.pkg.slp` replaced with the path to your training job package). See our guide to :ref:`remote_train` for more details.
+for each model you want to train (where `path/to/custom/profile.json` should be replaced with the path to your custom training profile and `path/to/dataset.pkg.slp` replaced with the path to your training job package). See our guide to [remote-train] for more details.
 
+```{note}
+If you exported the training package as a ZIP file, it contains both the `.pkg.slp` and `.json` files necessary to train with the configuration you selected in the GUI. Before running the [`sleap-train`](sleap-train) command, make sure to unzip this file.
+```