refactoring of sinatra apps; added quick-start doc section

.github/ISSUE_TEMPLATE.md

@@ -9,7 +9,7 @@
 - [ ] I did install/upgraded to the latest version of pagy (or the latest `3.*` for pagy legacy)
 - [ ] I am providing at least one of the following working and self-sufficient code support that can reproduce this issue:
    - [ ] plain ruby file that can run as `ruby my-problem.rb`
-   - [ ] edited copy of the single file [standalone_app.rb](https://github.com/ddnexus/pagy/blob/master/apps/standalone_app.ru)
+   - [ ] edited copy of the single file [pagy_standalone_app.ru](https://github.com/ddnexus/pagy/blob/master/apps/pagy_standalone_app.ru)
    - [ ] link of my own branch forked from one branch of the [pagy-rails app](https://github.com/benkoshy/pagy-rails)
    - [ ] link of a standalone `docker image` downloadable from a docker repository (e.g. dockerhub.com)
    - [ ] `docker-compose` file that can be run with `docker-compose up` (and doesn't need to be built because it uses only docker images and no local context)

apps/standalone_app.ru → apps/pagy_standalone_app.ru

@@ -1,10 +1,21 @@
 # frozen_string_literal: true
 
-# Self-contained, standalone sinatra app usable to easily reproduce any pagy issue
+# Self-contained, standalone Sinatra app usable to play with pagy
+# and/or easily reproduce any pagy issue.
 
-# USAGE: rerun -- rackup -o 0.0.0.0 -p 8080 apps/basic_app.ru
+# Copy this file in your own machine and
+# ensure rack is installed (or `gem install rack`)
 
-# Available at http://0.0.0.0:8080
+# USAGE:
+#    rackup -o 0.0.0.0 -p 8080 pagy_standalone_app.ru
+
+# ADVANCED USAGE (with automatic app reload if you edit it):
+#    gem install rerun
+#    rerun -- rackup -o 0.0.0.0 -p 8080 pagy_standalone_app.ru
+
+# Point your browser at http://0.0.0.0:8080
+
+# read the comment below to edit this app
 
 require 'bundler/inline'
 
@@ -15,7 +26,6 @@ gemfile true do
   gem 'oj'
   gem 'rack'
   gem 'pagy'
-  gem 'rerun'
   gem 'puma'
   gem 'sinatra'
   gem 'sinatra-contrib'
@@ -28,38 +38,30 @@ require 'pagy/extras/items'
 require 'pagy/extras/trim'
 Pagy::VARS[:trim] = false # opt-in trim
 
-# sinatra setup
-require 'sinatra/base'
-
 # sinatra application
+require 'sinatra/base'
 class PagyApp < Sinatra::Base
-
   configure do
     enable :inline_templates
   end
-
   include Pagy::Backend
-
-  # edit this section adding your own helpers as you need
+  # edit this section adding your own helpers as needed
   helpers do
     include Pagy::Frontend
   end
-
   get '/pagy.js' do
     content_type 'application/javascript'
     send_file Pagy.root.join('javascripts', 'pagy.js')
   end
-
-  # edit this action as you need
+  # edit this action as needed
   get '/' do
     collection = MockCollection.new
     @pagy, @records = pagy(collection)
-    erb :pagy_demo    # template available in the __END__ section as @@ pagy_issue
+    erb :pagy_demo    # template available in the __END__ section as @@ pagy_demo
   end
-
 end
 
-# simple array-based collection that acts as standard DB collection
+# simple array-based collection that acts as a standard DB collection
 # use it as a simple way to get a collection that acts as a AR scope, but without any DB
 # or create an ActiveRecord class or anything else that you need instead
 class MockCollection < Array
@@ -98,8 +100,8 @@ __END__
 
 
 @@ pagy_demo
-<h3>Pagy Standalone</h3>
-<p> Self-contained, standalone sinatra app usable to easily reproduce any pagy issue.</p>
+<h3>Pagy Standalone Application</h3>
+<p> Self-contained, standalone Sinatra app usable to play with pagy and/or easily reproduce any pagy issue.</p>
 <p>Please, report the following versions in any new issue.</p>
 <h4>Versions</h4>
 <ul>

docs/how-to.md

@@ -7,6 +7,19 @@ This page contains the practical tips and examples to get the job done with Pagy
 
 ## Quick Start
 
+### Play with it
+
+If you want to just play with Pagy before using it in your own app, you have 2 alternatives:
+
+1. Standalone Application
+   - Ensure to have `rack` installed (or `gem install rack`)
+   - [Use the pagy_standalone_app.ru](https://github.com/ddnexus/pagy/blob/master/apps/pagy_standalone_app.ru) (usage notes in the file)
+2. Pagy Console
+   - Just `gem install pagy`
+   - [Use it fully without any app](api/console.md)
+
+### Use it in your app
+
 1. Install Pagy:
 
     - If you use Bundler, add the gem in the Gemfile, optionally avoiding the next major version with breaking changes (e.g. '~> 3.5' see [RubyGem Specifiers](http://guides.rubygems.org/patterns/#pessimistic-version-constraint)):