Improve documentation

_config.yml

@@ -1,30 +1,94 @@
-title: DeepLabCut
-author: The DeepLabCut Team
-logo: docs/images/logo.png
-only_build_toc_files: true
+#######################################################################################
+# A default configuration that will be loaded for all jupyter books
+# Users are expected to override these values in their own `_config.yml` file.
+# This is also the "master list" of all allowed keys and values.
 
-sphinx:
-  config:
-    autodoc_mock_imports: ["wx"]
-    mermaid_output_format: raw
-  extra_extensions:
-    - numpydoc
-    - sphinxcontrib.mermaid
+#######################################################################################
+# Book settings
+title                       : DeepLabCut  # The title of the book. Will be placed in the left navbar.
+author                      : The DeepLabCut Team  # The author of the book
+copyright                   : "2023"  # Copyright year to be placed in the footer
+logo                        : "docs/images/logo.png"  # A path to the book logo
+# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb")
+exclude_patterns            : [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"]
+# Auto-exclude files not in the toc
+only_build_toc_files        : true
 
+#######################################################################################
+# Execution settings
 execute:
-  execute_notebooks: "off"
+  execute_notebooks         : off  # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off")
+  cache                     : ""    # A path to the jupyter cache that will be used to store execution artifacts. Defaults to `_build/.jupyter_cache/`
+  exclude_patterns          : []    # A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time)
+  timeout                   : 30    # The maximum time (in seconds) each notebook cell is allowed to run.
+  run_in_temp               : false # If `True`, then a temporary directory will be created and used as the command working directory (cwd),
+                                    # otherwise the notebook's parent directory will be the cwd.
+  allow_errors              : false # If `False`, when a code cell raises an error the execution is stopped, otherwise all cells are always run.
+  stderr_output             : show  # One of 'show', 'remove', 'remove-warn', 'warn', 'error', 'severe'
+
+#######################################################################################
+# Parse and render settings
+parse:
+  myst_enable_extensions:  # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    - amsmath
+    - colon_fence
+    - deflist
+    - dollarmath
+    - html_admonition
+    - html_image
+    - linkify
+    - replacements
+    - smartquotes
+    - substitution
+    - tasklist
+  myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links
+  myst_dmath_double_inline: true  # Allow display math ($$) within an inline context
 
+#######################################################################################
+# HTML-specific settings
 html:
-  extra_navbar: ""
-  use_issues_button: true
-  use_repository_button: true
-  extra_footer: |
-    <div>Powered by <a href="https://jupyterbook.org/">Jupyter Book</a>.</div>
+  favicon                   : ""  # A path to a favicon image
+  use_edit_page_button      : false  # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in
+  use_repository_button     : true  # Whether to add a link to your repository button
+  use_issues_button         : true  # Whether to add an "open an issue" button
+  use_multitoc_numbering    : true   # Continuous numbering across parts/chapters
+  extra_footer              : <div>Powered by <a href="https://jupyterbook.org/">Jupyter Book</a>.</div>  # Will be displayed underneath the footer.
+  google_analytics_id       : ""  # A GA id that can be used to track book views.
+  home_page_in_navbar       : true  # Whether to include your home page in the left Navigation Bar
+  baseurl                   : ""  # The base URL where your book will be hosted. Used for creating image previews and social links. e.g.: https://mypage.com/mybook/
+  analytics:
 
-repository:
-  url: https://github.com/DeepLabCut/DeepLabCut
-  path_to_book: docs
-  branch: main
+  comments:
+    hypothesis              : false
+    utterances              : false
+  announcement              : "" # A banner announcement at the top of the site.
+
+#######################################################################################
+# LaTeX-specific settings
+latex:
+  latex_engine              : pdflatex  # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
+  use_jupyterbook_latex     : true # use sphinx-jupyterbook-latex for pdf builds as default
 
+#######################################################################################
+# Launch button settings
 launch_buttons:
-  colab_url: "https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb"
+  notebook_interface        : classic  # The interface interactive links will activate ["classic", "jupyterlab"]
+  binderhub_url             : ""  # The URL of the BinderHub (e.g., https://mybinder.org)
+  jupyterhub_url            : ""  # The URL of the JupyterHub (e.g., https://datahub.berkeley.edu)
+  thebe                     : false  # Add a thebe button to pages (requires the repository to run on Binder)
+  colab_url                 : "https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb" # The URL of Google Colab (https://colab.research.google.com)
+
+repository:
+  url                       : https://github.com/DeepLabCut/DeepLabCut  # The URL to your book's repository
+  path_to_book              : "docs"  # A path to your book's folder, relative to the repository root.
+  branch                    : main  # Which branch of the repository should be used when creating links
+
+#######################################################################################
+# Advanced and power-user settings
+sphinx:
+  extra_extensions          : [numpydoc, sphinxcontrib.mermaid]  # A list of extra extensions to load by Sphinx (added to those already used by JB).
+  local_extensions          :   # A list of local extensions to load by sphinx specified by "name: path" items
+  recursive_update          : false # A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false)
+  config:   # key-value pairs to directly over-ride the Sphinx configuration
+    autodoc_mock_imports    : ["wx"]
+    mermaid_output_format   : raw

_toc.yml

@@ -1,28 +1,35 @@
 format: jb-book
-root: README
+root: docs/get_started
 parts:
-- caption: Getting Started
-  chapters:
-  - file: docs/UseOverviewGuide
-- caption: Installation
-  chapters:
-  - file: docs/installation
-  - file: docs/recipes/installTips
-  - file: docs/docker
-- caption: User Guides
-  chapters:
-  - file: docs/standardDeepLabCut_UserGuide
-  - file: docs/maDLC_UserGuide
-  - file: docs/Overviewof3D
+- caption:
+  chapters: 
+  - file: docs/project_types
+- caption: ⚙️ Installation
+  chapters:
+  - file: docs/installation/overview
+  - file: docs/installation/install_conda
+  - file: docs/installation/install_docker
+  # - file: docs/installation/install_windows
+  # - file: docs/installation/install_macos
+  # - file: docs/installation/install_linux
+  - file: docs/installation/install_tips
+  # - file: docs/installation/installation
+- caption: 🚴‍♀️ Usage
+  chapters:
+  - file: docs/usage/usage_gui
+  - file: docs/usage/usage_cli
+  - file: docs/usage/usage_napari
+- caption: 🚴‍♀️ Project types
+  chapters:
+  - file: docs/projects/project_overview
+  - file: docs/projects/project_single
+  - file: docs/projects/project_multi
+  - file: docs/projects/project_3D
+  - file: docs/projects/project_live
   - file: docs/HelperFunctions
-- caption: Graphical User Interfaces (GUIs)
+- caption: 📚 Guides
   chapters:
-  - file: docs/PROJECT_GUI
-  - file: docs/napari_GUI
   - file: docs/recipes/ClusteringNapari
-- caption: DeepLabCut-Live!
-  chapters:
-  - file: docs/deeplabcutlive
 - caption: DeepLabCut Model Zoo
   chapters:
   - file: docs/ModelZoo
@@ -34,7 +41,7 @@ parts:
 - caption: Hardware
   chapters:
   - file: docs/recipes/TechHardware
-- caption: Tutorials & Cookbook
+- caption: 📚 Tutorials & Cookbook
   chapters:
   - file: docs/tutorial
   - file: docs/convert_maDLC

docs/README.md

@@ -1,3 +1,7 @@
 Please see https://deeplabcut.github.io/DeepLabCut for documentation on how to use this software. 
 
 This directory contains the source code for the docs.
+
+To contribute to the docs, install the developer edition of DeepLabCut. Install additional dependencies (`jupyter-book`, `sphinxcontrib-mermaid`).
+
+To build the documentation, from the root folder (`DeepLabCut`), run `jupyter-book build .`.

docs/UseOverviewGuide.md → docs/get_started.md

@@ -1,10 +1,29 @@
 (overview)=
-# 🥳 Get started with DeepLabCut: our key recommendations 
+# 🚀 Get started
+We know - you can't wait to get started doing some awesome tracking! And you don't have long to go - **but wait a moment before installing, read on, and follow the guide in the order it's written - it'll save you a lot of troubles**. 
 
+DeepLabCut has grown into a whole ecosystem of pose estimation tools. This ecosystem 
 Below we will first outline what you need to get started, the different ways you can use DeepLabCut, and then the full workflow. Note, we highly recommend you also read and follow our [Nature Protocols paper](https://www.nature.com/articles/s41596-019-0176-0), which is (still) fully relevant to standard DeepLabCut.
 
-## [How to install DeepLabCut](how-to-install)
+## [Installation](how-to-install)
+Now, we can move on to installation. DeepLabCut can be run on **Windows**, **Linux**, or **MacOS**. We provide multiple ways to install, but the two main ways are using either a `conda`-based installation (**recommended**) [`Docker` container](docker-containers) (recommended for Ubuntu advanced users). 
 
+**Our recommended route is to use `conda`**.
+
+::::{grid}
+:gutter: 2
+
+:::{grid-item-card} [Install with `conda`](install-conda)
+[![alt](images/conda_logo.svg)](install-conda)
+:::
+
+:::{grid-item-card} [Install with `Docker`](install-docker)
+[![alt](images/docker_logo.svg)](install-docker)
+:::
+
+::::
+
+## Usage
 - Decide on your needs: there are **two main modes, standard DeepLabCut or multi-animal DeepLabCut**. We highly recommend carefully considering which one is best for your needs. For example, a white mouse + black mouse would call for standard, while two black mice would use multi-animal. **[Important Information on how to use DLC in different scenarios (single vs multi animal)](important-info-regd-usage)** Then pick:
 
 - (1) [How to use standard DeepLabCut](single-animal-userguide)