Merge pull request #75 from Caltech-IPAC/FIREFLY-1573-py-upload

FIREFLY-1573: Extend Firefly python's file (up)loading API

Author: jaladh-singhal

README.md

@@ -1,26 +1,12 @@
 # firefly_client
 
-Python API for Firefly, IPAC's Advanced Astronomy Web UI Framework
+Python API for [Firefly](http://github.com/Caltech-IPAC/firefly), IPAC's Advanced Astronomy Web UI Framework. This allows users to leverage Firefly in their Python notebooks for interactive exploration of astronomical data (images, catalogs, charts, regions, and more) with just a couple of lines of code.
 
-## Usage
 
-The client must be connected to a Firefly server. The Firefly
-repository is located at http://github.com/Caltech-IPAC/firefly.
-Standalone Firefly servers may be obtained from
-[this Dockerhub repository](https://hub.docker.com/r/ipac/firefly/).
+## Documentation
 
-For detailed explanation on the usage, see [the online documentation](https://caltech-ipac.github.io/firefly_client). Following is a very simple example:
+You can find the documentation at https://caltech-ipac.github.io/firefly_client.
 
-```
-from firefly_client import FireflyClient
-fc = FireflyClient.make_client()  # can also explictly pass url of a firefly server; default is http://localhost:8080/firefly
-```
+NOTE: Many parts of this documentation are a work in progress because the firefly_client API and its use cases evolved since it was written.
+Please report any issues or suggestions on the [GitHub issues](https://github.com/Caltech-IPAC/firefly_client/issues).
 
-A FITS image may be uploaded and displayed:
-
-```
-fval = fc.upload_file('image.fits')
-fc.show_fits(fval, 'myimage')
-```
-
-For more examples, check notebooks & python files in the [examples](examples/) and [test](test/) directories.

docs/usage/demo-notebooks.rst

@@ -0,0 +1,37 @@
+###############
+Demo Notebooks
+###############
+
+
+Reference Guide
+-----------------
+
+For a high-level overview of the Firefly Python client API and important methods, refer to this `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 tutorial notebooks demonstrates the use of Firefly Python client:
+
+- `Using Firefly visualization tools in Python to vet SEDs <https://caltech-ipac.github.io/irsa-tutorials/tutorials/firefly/SEDs_in_Firefly.html>`_
+- `Using Firefly visualization tools to understand the light curves of Solar System objects <https://caltech-ipac.github.io/irsa-tutorials/tutorials/firefly/NEOWISE_light_curve_demo.html>`_
+- `Using Firefly to Explore OpenUniverse2024 Data Preview Simulated Roman and Rubin Images <https://caltech-ipac.github.io/irsa-tutorials/tutorials/firefly/OpenUniverse2024Preview_Firefly.html>`_
+- `Euclid Q1: PHZ catalogs — Visualize with Firefly section <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