Add a reference notebook and update demo notebooks in TOC

Author: jaladh-singhal

docs/usage/demo-notebooks.rst

@@ -0,0 +1,39 @@
+###############
+Demo Notebooks
+###############
+
+
+Reference Guide
+-----------------
+
+For a high-level overview of the Firefly Python client API and important methods, refer to this `reference guide notebook`.
+
+.. _`reference guide notebook`:
+    https://nbviewer.org/github/Caltech-IPAC/firefly_client/tree/master/examples/reference-guide.ipynb.
+
+
+Science Use-cases
+-----------------
+
+IRSA Tutorials is collection of multiple notebooks that demonstrate the use of IRSA data services and tools for science use-cases.
+The following notebook demonstrates the use of Firefly Python Client:
+- https://caltech-ipac.github.io/irsa-tutorials/tutorials/firefly/SEDs_in_Firefly.html
+- https://caltech-ipac.github.io/irsa-tutorials/tutorials/firefly/NEOWISE_light_curve_demo.html
+- https://caltech-ipac.github.io/irsa-tutorials/tutorials/firefly/OpenUniverse2024Preview_Firefly.html
+- https://caltech-ipac.github.io/irsa-tutorials/tutorials/euclid_access/4_Euclid_intro_PHZ_catalog.html#vizualize-the-image-with-firefly
+
+
+Other Examples
+---------------
+
+For a full list of notebooks/scripts that demonstrate the use of
+Firefly Python client, refer to |nbviewer_examples| (rendered in nbviewer).
+
+.. warning::
+    Several of the notebooks in the examples directory use deprecated API (or discouraged API that is about to be deprecated) and will be updated soon.
+
+
+.. |nbviewer_examples| raw:: html
+
+   <a href="https://nbviewer.org/github/Caltech-IPAC/firefly_client/tree/master/examples/"
+   target="_blank">this examples directory</a>

docs/usage/index.rst

@@ -12,15 +12,4 @@ Using firefly_client
    viewing-tables
    charting
    callbacks-extensions
-
-
-Examples
---------
-
-You can find a list of notebooks/scripts that demonstrate the use of
-firefly_client in |nbviewer_examples|. 
-
-.. |nbviewer_examples| raw:: html
-
-   <a href="https://nbviewer.org/github/Caltech-IPAC/firefly_client/tree/master/examples/"
-   target="_blank">this directory (rendered in nbviewer)</a>
+   demo-notebooks