Update documentation for using nightly releases. (#567)

Hopefully this helps with issues like
#544

Author: ScottTodd

docs/nightly_releases.md

@@ -1,12 +1,5 @@
 # Nightly releases
 
-> [!WARNING]
-> This is still under development! See
-> https://github.com/nod-ai/shark-ai/issues/400.
->
-> These instructions will be converted into a user guide once stable packages
-> are published to PyPI: <https://github.com/nod-ai/shark-ai/issues/359>.
-
 Nightly releases are uploaded to
 https://github.com/nod-ai/shark-ai/releases/tag/dev-wheels.
 
@@ -51,11 +44,9 @@ which python3.11
 # /usr/bin/python3.11
 ```
 
-> [!NOTE]
-> Tip: manage multiple Python versions using `pyenv`
-> (<https://github.com/pyenv/pyenv>), or `update-alternatives` on Linux
-> ([guide here](https://linuxconfig.org/how-to-change-from-default-to-alternative-python-version-on-debian-linux))
-> , or the
+> [!TIP]
+> Manage multiple Python versions using `pyenv`
+> (<https://github.com/pyenv/pyenv>), or the
 > [Python Launcher for Windows](https://docs.python.org/3/using/windows.html#python-launcher-for-windows)
 > on Windows.
 
@@ -117,3 +108,106 @@ pip install -f https://iree.dev/pip-release-links.html --upgrade --pre \
   iree-base-compiler iree-base-runtime --src deps \
   -e "git+https://github.com/iree-org/iree-turbine.git#egg=iree-turbine"
 ```
+
+## Switching between stable and nightly channels
+
+The [`shark-ai` package on PyPI](https://pypi.org/project/shark-ai/) is a
+meta-package that pins specific stable versions of each package that share
+at least their major and minor versions:
+
+```bash
+pip install shark-ai==2.9.1
+
+pip freeze
+# ...
+# iree-base-compiler==2.9.0
+# iree-base-runtime==2.9.0
+# iree-turbine==2.9.0
+# ...
+# shark-ai==2.9.1
+# shortfin==2.9.1
+# ...
+```
+
+If you attempt to update any individual package outside of those supported
+versions, pip will log an error but continue anyway:
+
+```bash
+pip install --upgrade --pre \
+  -f https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels \
+  shortfin==3.0.0rc20241118
+
+# Looking in links: https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels
+# Collecting shortfin==3.0.0rc20241118
+#   Downloading https://github.com/nod-ai/shark-ai/releases/download/dev-wheels/shortfin-3.0.0rc20241118-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB)
+#      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.5/2.5 MB 24.3 MB/s eta 0:00:00
+# Installing collected packages: shortfin
+#   Attempting uninstall: shortfin
+#     Found existing installation: shortfin 2.9.1
+#     Uninstalling shortfin-2.9.1:
+#       Successfully uninstalled shortfin-2.9.1
+# ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
+# shark-ai 2.9.1 requires shortfin==2.9.1, but you have shortfin 3.0.0rc20241118 which is incompatible.
+# Successfully installed shortfin-3.0.0rc20241118
+
+pip freeze
+# ...
+# shark-ai==2.9.1
+# shortfin==3.0.0rc20241118
+# ...
+```
+
+Installing the `shark-ai` package again should get back to aligned versions:
+
+```bash
+pip install shark-ai==2.9.1
+# ...
+# Installing collected packages: shortfin
+#   Attempting uninstall: shortfin
+#     Found existing installation: shortfin 3.0.0rc20241118
+#     Uninstalling shortfin-3.0.0rc20241118:
+#       Successfully uninstalled shortfin-3.0.0rc20241118
+# Successfully installed shortfin-2.9.1
+
+pip freeze
+# ...
+# shark-ai==2.9.1
+# shortfin==2.9.1
+# ...
+```
+
+You can also uninstall the `shark-ai` package to bypass the error and take full
+control of package versions yourself:
+
+```bash
+pip uninstall shark-ai
+
+pip freeze
+# ...
+# (note: no shark-ai package)
+# shortfin==2.9.1
+# ...
+
+pip install --upgrade --pre \
+  -f https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels \
+  shortfin==3.0.0rc20241118
+
+# Looking in links: https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels
+# Collecting shortfin==3.0.0rc20241118
+#   Using cached https://github.com/nod-ai/shark-ai/releases/download/dev-wheels/shortfin-3.0.0rc20241118-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB)
+# Installing collected packages: shortfin
+#   Attempting uninstall: shortfin
+#     Found existing installation: shortfin 2.9.1
+#     Uninstalling shortfin-2.9.1:
+#       Successfully uninstalled shortfin-2.9.1
+# Successfully installed shortfin-3.0.0rc20241118
+
+pip freeze
+# ...
+# (note: no shark-ai package)
+# shortfin==3.0.0rc20241118
+# ...
+```
+
+If you ever get stuck, consider creating a fresh
+[virtual environment](https://docs.python.org/3/library/venv.html).

docs/user_guide.md

@@ -1,9 +1,5 @@
 # SHARK User Guide
 
-> [!WARNING]
-> This is still pre-release so the artifacts listed here may be broken
->
-
 These instructions cover the usage of the latest stable release of SHARK. For a more bleeding edge release please install the [nightly releases](nightly_releases.md).
 
 ## Prerequisites
@@ -12,7 +8,6 @@ Our current user guide requires that you have:
 - Access to a computer with an installed AMD Instinct™ MI300x Series Accelerator
 - Installed a compatible version of Linux and ROCm on the computer (see the [ROCm compatability matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html))
 
-
 ## Set up Environment
 
 This section will help you install Python and set up a Python environment with venv.
@@ -51,11 +46,9 @@ pip install torch torchvision torchaudio --index-url https://download.pytorch.or
 pip install shark-ai[apps]
 ```
 
-Temporarily, you may need an update to your `shortfin` install.
-Install the latest pre-release with:
-```
-pip install shortfin --upgrade --pre -f https://github.com/nod-ai/shark-ai/releases/expanded_assets/dev-wheels
-```
+> [!TIP]
+> To switch from the stable release channel to the nightly release channel,
+> see [`nightly_releases.md`](./nightly_releases.md).
 
 ### Test the installation.