Merge pull request #29 from rdytech/NEP-18355-update-docs

jbat · web-flow · commit 308d1596cac2 · 2024-08-07T07:19:49.000+10:00
NEP-18355 Update docs
diff --git a/README.md b/README.md
@@ -8,6 +8,12 @@ All ruby classes are namespaced under `Superset::`
 
 # Installation
 
+## Setup API Credentials
+
+Follow this to [setup your users API creds](https://github.com/rdytech/superset-client/tree/develop/doc/setting_up_personal_api_credentials.md)
+
+Short version is .. copy the `env.sample` to `.env` and add edit values where applicable.  Opening a console with `bin/console` will then auto load the `.env` file.
+
 ## Docker Setup
 
 Build, bundle and open a ruby console
@@ -18,188 +24,69 @@ docker-compose run --rm app bundle install
 docker-compose run --rm app bin/console
 ```
 
-Run specs
+## Setup Locally ( no docker ) 
+
+Requires Ruby >= 2.6.0 
+
+Bundle install and open a ruby console.
 
 ```
-docker-compose run --rm app rspec
-# or 
-docker-compose run --rm app bash      # then run 'bundle exec rspec' from the container.
+bundle install
+bin/console
 ```
 
-## Local setup or including in a Ruby/Rails app
+## Including in a Ruby app
 
 Add to your Gemfile `gem 'superset'`  
 And then execute: `bundle install`  
 Or install it yourself as `gem install superset`
 
-## Setup API Credentials
+## Run specs
 
-Follow this doc setup your users API creds [setting_up_personal_api_credentials](https://github.com/rdytech/superset-client/tree/develop/doc/setting_up_personal_api_credentials.md)
+```
+docker-compose run --rm app rspec
+# or 
+docker-compose run --rm app bash      # then run 'bundle exec rspec' from the container.
+```
 
-Short version is .. copy the `env.sample` to `.env` and add edit values where applicable.  Opening a console with `bin/console` will then auto load the `.env` file.
 
 ## Usage
 
-Experiment with the API calls directly by open a pry console using  `bin/console`
-
-
-
-
-### API calls
-
-Quickstart examples
+Experiment with the API calls directly by open a pry console using  `bin/console`.
 
 ```ruby
-Superset::Database::List.call
-Superset::Database::GetSchemas.new(1).list # get schemas for database 1
-
 Superset::Dashboard::List.call
-Superset::Dashboard::List.new(title_contains: 'Sales').list
-
-Superset::Dashboard::BulkDelete.new(dashboard_ids: [1,2,3]).perform        # Dashboards only ( leaves all charts, datasets in place)
-Superset::Dashboard::BulkDeleteCascade.new(dashboard_ids: [1,2,3]).perform # Dashboards and related charts and datasets.
-
-Superset::Sqllab::Execute.new(database_id: 1, schema: 'public', query: 'select count(*) from birth_names').perform
-
-Superset::Dashboard::Export.new(dashboard_id: 1, destination_path: '/tmp').perform
-
-Superset::RouteInfo.new(route: 'dashboard/_info').perform # Get info on an API endpoint .. handy for getting available filters
-Superset::RouteInfo.new(route: 'chart/_info').filters     # OR just get the filters for an endpoint
 
 superset_class_list # helper method to list all classes under Superset::
-
+sshelp              # aliased for superset_class_list
 ```
 
-### Duplicating Dashboards
-
-Primary motivation behind this library was to use the Superset API to duplicate dashboards, charts, datasets across multiple database connections.  
-See examples in [Duplicate Dashboards](https://github.com/rdytech/superset-client/tree/develop/doc/duplicate_dashboards.md)
-
-### API Examples with results
-
-Generally classes follow the convention/path of the Superset API strucuture as per the swagger docs.
-
-ref https://superset.apache.org/docs/api/
-
-Limited support for filters is available on some list pages, primarily through param `title_contains`.  
-Pagination is supported via `page_num` param.
-
-Primary methods across majority of api calls are
-- response : the full API response
-- result : just the result attribute array
-- list : displays a formatted output to console, handy for quick investigation of objects
-- call : is a class method to list on Get and List requests
-
-```ruby
-# List all Databases
-Superset::Database::List.call
-# DEBUG -- : Happi: GET https://your-superset-host/api/v1/database/?q=(page:0,page_size:100), {}
-+----+------------------------------------+------------+------------------+
-|                        Superset::Database::List                         |
-+----+------------------------------------+------------+------------------+
-| Id | Database name                      | Backend    | Expose in sqllab |
-+----+------------------------------------+------------+------------------+
-| 1  | examples                           | postgresql | true             |
-+----+------------------------------------+------------+------------------+
-
-# List database schemas for Database 1
-Superset::Database::GetSchemas.new(1).list
-# DEBUG -- : Happi: GET https://your-superset-host/api/v1/database/1/schemas/, {}
-=> ["information_schema", "public"]
-
-# List dashboards
-Superset::Dashboard::List.call
-# PAGE_SIZE is set to 100, so get the second set of 100 dashboards with
-Superset::Dashboard::List.new(page_num: 1).list
-# OR filter by title
-Superset::Dashboard::List.new(title_contains: 'Sales').list
-# DEBUG -- : Happi: GET https://your-superset-host/api/v1/dashboard/?q=(filters:!((col:dashboard_title,opr:ct,value:'Sales')),page:0,page_size:100), {}
-
-+-----+------------------------------+-----------+--------------------------------------------------------------------+
-|                                              Superset::Dashboard::List                                              |
-+-----+------------------------------+-----------+--------------------------------------------------------------------+
-| Id  | Dashboard title              | Status    | Url                                                                |
-+-----+------------------------------+-----------+--------------------------------------------------------------------+
-| 6   | Video Game Sales             | published | https://your-superset-host/superset/dashboard/6/                   |
-| 8   | Sales Dashboard              | published | https://your-superset-host/superset/dashboard/8/                   |
-+-----+------------------------------+-----------+--------------------------------------------------------------------+
-
-
-Superset::Dashboard::Get.call(1)  # same as Superset::Dashboard::Get.new(1).list
-+----------------------------+
-|     World Banks Data      |
-+----------------------------+
-| Charts                     |
-+----------------------------+
-| % Rural                    |
-| Region Filter              |
-| Life Expectancy VS Rural % |
-| Box plot                   |
-| Most Populated Countries   |
-| Worlds Population          |
-| Worlds Pop Growth          |
-| Rural Breakdown            |
-| Treemap                    |
-| Growth Rate                |
-+----------------------------+
-
+More examples [listed here](https://github.com/rdytech/superset-client/tree/develop/doc/usage.md)
 
-```
-## Optional Credential setup for Embedded User
 
-Primary usage is for api calls and/or for guest token retrieval when setting up applications to use the superset embedded dashboard workflow.
+## Duplicating Dashboards
 
-The Superset API users fall into 2 categories  
-- a user for general api calls to endpoints for Dashboards, Datasets, Charts, Users, Roles etc.  
-  ref `Superset::Credential::ApiUser`  
-  which pulls credentials from  `ENV['SUPERSET_API_USERNAME']` and `ENV['SUPERSET_API_PASSWORD']`
+The Primary motivation behind this gem was to use the Superset API to duplicate dashboards, charts, datasets across multiple database connections.  
 
-- a user for guest token api call to use when embedding dashboards in a host application.  
-  ref `Superset::Credential::EmbeddedUser`
-  which pulls credentials from  `ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
+Targeted use case was for superset embedded functionality implemented in a application resting on multi tenanted database setup.
 
+See examples in [Duplicate Dashboards](https://github.com/rdytech/superset-client/tree/develop/doc/duplicate_dashboards.md)
 
-### Fetch a Guest Token for Embedded user
 
-Assuming you have setup your Dashboard in Superset to be embedded and that your creds are setup in  
-`ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
+## Contributing
 
-```
-Superset::GuestToken.new(embedded_dashboard_id: '15').guest_token
-=> "eyJ0eXAiOi............VV4mrMfsvg"
-```
+- Fork it
+- Create your feature branch (git checkout -b my-new-feature)
+- Commit your changes (git commit -am 'Add some feature')
+- Push to the branch (git push origin my-new-feature)
+- Create new Pull Request
 
-## Releasing a new version
 
-On develop branch make sure to update `Superset::VERSION` and `CHANGELOG.md` with the new version number and changes.  
-Build the new version and upload to gemfury.
-
-`gem build superset.gemspec`
 
 ### Publishing to RubyGems
 
 WIP .. direction is for this gem to be made public
 
-### ReadyTech private Gemfury repo
-
-ReadyTech hosts its own private gemfury remote repo.
-
-Get the latest develop into master
-
-    git checkout master
-    git pull
-    git fetch
-    git merge origin/develop
-
-Tag the version and push to github
-
-    git tag -a -m "Version 0.1.0" v0.1.0
-    git push origin master --tags
-
-Push to gemfury or upload the build manually in the gemfury site.
-
-    git push fury master
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
diff --git a/bin/console b/bin/console
@@ -45,7 +45,7 @@ end
 
 unless ENV['SUPERSET_HOST'] && ENV['SUPERSET_API_USERNAME'] && ENV['SUPERSET_API_PASSWORD']
   puts "Missing environment variables.  Check your .env file"
-  puts "Please set each value for SUPERSET_HOST, SUPERSET_API_USERNAME, and SUPERSET_API_PASSWORD values"
+  puts "All env vars are required for SUPERSET_HOST, SUPERSET_API_USERNAME, and SUPERSET_API_PASSWORD values"
   puts "Refer to ./doc/setting_up_personal_api_credentials.md for more info"
   exit
 end
@@ -63,11 +63,13 @@ end
 
 # general help to list all superset classes
 def superset_class_list
-  puts " ---- Listing Superset Classes ----- "
+  puts " ---- Listing Superset ruby client API Classes ----- "
   list_classes(Superset)
 end
+alias :sshelp :superset_class_list
 
 puts "\n  >>> Welcome to the Superset Ruby API Client <<< \n\n"
+puts "\n  >>> list all available classes with 'sshelp' <<< \n\n"
 puts "Your accessible Superset Database connections are: Superset::Database::List.call"
 
 Superset::Database::List.call
diff --git a/doc/publishing.md b/doc/publishing.md
@@ -0,0 +1,39 @@
+# Publishing
+
+The team at ReadyTech currently manages the gem and new version releases.
+
+As per demand / usage of the public gem, the team at ReadyTech will soon move to primarily hosting
+the gem on RubyGems.
+
+Until then, ReadyTech will continue to host a private Gemfury version as well as RubyGems.
+
+
+## ReadyTech private Gemfury repo
+
+### Releasing a new version
+
+On develop branch make sure to update `Superset::VERSION` and `CHANGELOG.md` with the new version number and changes.  
+
+Build the new version and upload to gemfury.
+
+`gem build superset.gemspec`
+
+### Publish to Gemfury
+
+ReadyTech hosts its own private gemfury remote repo.
+
+Get the latest develop into master
+
+    git checkout master
+    git pull
+    git fetch
+    git merge origin/develop
+
+Tag the version and push to github
+
+    git tag -a -m "Version 0.1.0" v0.1.0
+    git push origin master --tags
+
+Push to gemfury or upload the build manually in the gemfury site.
+
+    git push fury master
diff --git a/doc/setting_up_personal_api_credentials.md b/doc/setting_up_personal_api_credentials.md
@@ -26,17 +26,19 @@ Starting a ruby console with `bin/console` will auto load the env vars.
 
 If your Superset instance is setup to authenicate via SSO then your authenticating agent will most likely have provided a username for you in the form of a UUID value.
 
-This is easily retrieved on you User Profile page in Superset.
+This is easily retrieved on your user profile page in Superset.
 
-Optionally use jinja template macro in sql lab.
+Optionally use the jinja template macro in sql lab.
 
 ```
 select '{{ current_username() }}' as current_username;
 ```
 
+Then plug your username in to the .env file.
+
 ## Creating / Updating your password via Swagger interface
 
-A common setup is to use SSO to enable user access in Superset.  This would mean your authenticating agent is your SSO provider service ( ie Azure ) and most likely you do not have / need a password configured for your Superset user for GUI access.
+A common setup is to use SSO to enable user access in Superset.  This would mean your authenticating agent is your SSO provider service ( ie Azure etc ) and most likely you do not have / need a password configured for your Superset user for GUI access.
 
 If this is the case, you will need to add your own password via hitting the superset API using the swagger interface.
 
@@ -50,7 +52,7 @@ select '{{ current_user_id() }}' as current_user_id;
 ```
 - ask your superset admin to tell you what your personal superset user id is.
 
-Once you have your user id value, open the Swagger API page on you superset host.  
+Once you have your user id value, open the Swagger API page on your superset host.  
 `https://{your-superset-host}/swagger/v1`
 
 Scroll down to the 'Security Users' area and find the PUT request that will update your users record.
@@ -78,7 +80,7 @@ Given some local development requirements where you have to access multiple supe
 Just set the overall superset environment in `.env`
 
 ```
-# .env file holding one setting for the overall superset environment
+# .env file holding one setting for the superset environment your accessing
 SUPERSET_ENVIRONMENT='staging'
 ```
 
@@ -101,11 +103,22 @@ SUPERSET_API_USERNAME="production-user-here"
 SUPERSET_API_PASSWORD="set-password-here"
 ```
 
-The command `bin/console` will then load your env file depending on the value in ENV['SUPERSET_ENVIRONMENT'] from the primary `.env`.
+And again, for localhost if required to perform api call in you local dev environment.
+Create a new file called `.env-localhost` that holds your superset development host and credentials.
+
+```
+# specific settings for the superset localhost env
+SUPERSET_HOST="http://localhost:8080/"
+SUPERSET_API_USERNAME="dev-user-here"
+SUPERSET_API_PASSWORD="set-password-here"
+```
+
+
+The command `bin/console` will then load your env file depending on the value in ENV['SUPERSET_ENVIRONMENT'] from the primary `.env` file.
 
 When you need to switch envs, exit the console, edit the .env to your desired value, eg `production`, then open a console again.
 
-Bonus is the Pry prompt will now also include the `SUPERSET_ENVIRONMENT` value.
+The ruby prompt will now also include the `SUPERSET_ENVIRONMENT` value.
 
 ```
 bin/console
@@ -122,6 +135,29 @@ Happi: GET https://your-staging-superset-host.com/api/v1/dashboard/?q=(filters:!
 +----+------------------+-----------+------------------------------------------------------------------+
 ```
 
+## Optional Credential setup for Embedded User
+
+Primary usage is for api calls and/or for guest token retrieval when setting up applications to use the superset embedded dashboard workflow.
+
+The Superset API users fall into 2 categories  
+- a user for general api calls to endpoints for Dashboards, Datasets, Charts, Users, Roles etc.  
+  ref `Superset::Credential::ApiUser`  
+  which pulls credentials from  `ENV['SUPERSET_API_USERNAME']` and `ENV['SUPERSET_API_PASSWORD']`
+
+- a user for guest token api call to use when embedding dashboards in a host application.  
+  ref `Superset::Credential::EmbeddedUser`
+  which pulls credentials from  `ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
+
+
+### Fetch a Guest Token for Embedded user
+
+Assuming you have setup your Dashboard in Superset to be embedded and that your creds are setup in  
+`ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
+
+```
+Superset::GuestToken.new(embedded_dashboard_id: '15').guest_token
+=> "eyJ0eXAiOi............VV4mrMfsvg"
+```
 
 
 
diff --git a/doc/usage.md b/doc/usage.md
diff --git a/env.sample b/env.sample
