From b7de3649d012066fdf4b603c5c7c087931dc7c30 Mon Sep 17 00:00:00 2001
From: Jeffrey Aven <javen@avensolutions.com>
Date: Thu, 12 Oct 2023 17:27:55 +1100
Subject: [PATCH] updated docs

---
 docs/source/index.rst     | 49 +++++++++++++--------------
 docs/source/magic_ext.rst | 69 +++++++++++++++++++++++++++++++++++++++
 docs/source/pystackql.rst | 12 -------
 3 files changed, 94 insertions(+), 36 deletions(-)
 create mode 100644 docs/source/magic_ext.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 68ffdd7..bab138a 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,25 +1,26 @@
-.. _StackQL: https://github.com/stackql/stackql
-
-pystackql documentation
-=======================
-`StackQL`_ is a dev tool which allows you to query and interact with cloud provider APIs using a SQL language. 
-StackQL can be used for cloud inventory analysis, security audits, Infrastructure-as-Code, lifecycle operations (such as starting or stopping a VM).
-
-The :mod:`pystackql` package is a Python library for using `StackQL <https://github.com/stackql/stackql>`_.
-For information on the StackQL language specification, grammar and built-in functions, see the `StackQL documentation <https://stackql.io/docs>`_.
-For StackQL provider information, see the `StackQL Provider Registry <https://registry.stackql.io/>`_.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents
-   
-   intro
-   examples
-   pystackql   
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
+.. _StackQL: https://github.com/stackql/stackql
+
+pystackql documentation
+=======================
+`StackQL`_ is a dev tool which allows you to query and interact with cloud provider APIs using a SQL language. 
+StackQL can be used for cloud inventory analysis, security audits, Infrastructure-as-Code, lifecycle operations (such as starting or stopping a VM).
+
+The :mod:`pystackql` package is a Python library for using `StackQL <https://github.com/stackql/stackql>`_.
+For information on the StackQL language specification, grammar and built-in functions, see the `StackQL documentation <https://stackql.io/docs>`_.
+For StackQL provider information, see the `StackQL Provider Registry <https://registry.stackql.io/>`_.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+   
+   intro
+   examples
+   pystackql  
+   magic_ext 
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
 * :ref:`search`
\ No newline at end of file
diff --git a/docs/source/magic_ext.rst b/docs/source/magic_ext.rst
new file mode 100644
index 0000000..93961de
--- /dev/null
+++ b/docs/source/magic_ext.rst
@@ -0,0 +1,69 @@
+StackqlMagic Extension for Jupyter
+==================================
+
+The ``StackqlMagic`` extension for Jupyter notebooks provides a convenient interface to run SQL queries against the StackQL database directly from within the notebook environment. Results can be visualized in a tabular format using Pandas DataFrames.
+
+Setup
+-----
+
+To enable the `StackqlMagic` extension in your Jupyter notebook, use the following command:
+
+.. code-block:: python
+
+    %load_ext pystackql
+
+Usage
+-----
+
+The extension provides both line and cell magic functionalities:
+
+1. **Line Magic**:
+    
+   You can run StackQL queries directly from a single line:
+
+   .. code-block:: python
+
+       %stackql DESCRIBE aws.ec2.instances
+
+2. **Cell Magic**:
+   
+   For multi-line queries or when you need to use specific options:
+
+   .. code-block:: python
+
+        %%stackql
+        SELECT instanceType, COUNT(*) as num_instances
+        FROM aws.ec2.instances 
+        WHERE region = '$region' GROUP BY instanceType       
+
+Options
+-------
+
+When using `StackqlMagic` as cell magic, you can pass in the following options:
+
+- **--no-display** : Suppresses the display of the results. Even when this option is enabled, the results are still saved in the `stackql_df` Pandas DataFrame.
+
+Example:
+
+.. code-block:: python
+
+    project = 'stackql-demo'
+    zone = 'australia-southeast1-a'
+    region = 'australia-southeast1'
+
+.. code-block:: python
+
+    %%stackql --no-display
+    SELECT name, status
+    FROM google.compute.instances 
+    WHERE project = '$project' AND zone = '$zone'
+
+This will run the query but won't display the results in the notebook. Instead, you can later access the results via the `stackql_df` variable.
+
+.. note::
+
+    The results of the queries are always saved in a Pandas DataFrame named `stackql_df` in the notebook's current namespace. This allows you to further process or visualize the data as needed.
+
+--------
+
+This documentation provides a basic overview and usage guide for the `StackqlMagic` extension. For advanced usage or any additional features provided by the extension, refer to the source code or any other accompanying documentation.
diff --git a/docs/source/pystackql.rst b/docs/source/pystackql.rst
index e1d5502..b6c9b5f 100644
--- a/docs/source/pystackql.rst
+++ b/docs/source/pystackql.rst
@@ -1,12 +1,6 @@
 API Reference for pystackql
 ===========================
 
-Module Contents
----------------
-.. automodule:: pystackql
-   :members:
-   :undoc-members:
-
 StackQL Class
 -------------
 .. autoclass:: pystackql.StackQL
@@ -15,10 +9,4 @@ StackQL Class
     :undoc-members:
     :show-inheritance:
 
-StackqlMagic Class (Jupyter Magic Extension)
---------------------------------------------
-.. autoclass:: pystackql.stackql_magic.StackqlMagic
-   :members:
-   :undoc-members:
-   :show-inheritance: