docs fixes and improvements

README.md

@@ -28,7 +28,7 @@ The values shown in the charts below have been recorded while each gem was produ
 
 _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#efficiency-ratio) is calculated out of speed (IPS) and Memory (Kb): it shows how well each gem uses any Kb of memory it allocates/consumes._
 
-#### Pagy does not suffer the typical limitations of the other gems:
+#### Pagy does not suffer the typical limitations of the other gems
 
 - it works with collections/scopes that already used `limit` and `offset`
 - it works with both helpers or templates (your choice)
@@ -115,6 +115,10 @@ Pagy is a fresh project and your help would be great. If you like it, you have a
 - submit a pull request to make pagy even faster, save more memory or improve its usability
 - create an issue if anything should be improved/fixed
 
+## Branches and Pull Requests
+
+`master` is the latest rubygem-published release: you should use it as the base branch for pull requests, because it will not be force-rebased. `dev` is the development branch that will receive your pull requests, and that get merged into `master` before a new release. Expect `dev` to be force-rebased, so it's probably wise not to use it as the base for your commits.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

docs/_layouts/default.html

@@ -36,6 +36,7 @@
       <a href="{{ site.baseurl }}/pagy-extras/bootstrap"><p class="indent1" {% if page.title == 'Bootstrap' %}id="active"{% endif %} >Bootstrap</p></a>
       <a href="{{ site.baseurl }}/pagy-extras/responsive"><p class="indent1" {% if page.title == 'Responsive' %}id="active"{% endif %} >Responsive</p></a>
       <a href="{{ site.baseurl }}/pagy-extras/compact"><p class="indent1" {% if page.title == 'Compact' %}id="active"{% endif %} >Compact</p></a>
+      <a href="{{ site.baseurl }}/migration-tips"><p {% if page.title == 'Migration Tips' %}id="active"{% endif %} >Migration Tips</p></a>
       <p id="gitter-badge"><a href="https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" rel="nofollow" target="_blank"><img src="https://camo.githubusercontent.com/1adf5e58915e2093fd2e856136ae26c99e2ae214/68747470733a2f2f6261646765732e6769747465722e696d2f727562792d706167792f4c6f6262792e737667" alt="Join the chat at https://gitter.im/ruby-pagy/Lobby" data-canonical-src="https://badges.gitter.im/ruby-pagy/Lobby.svg" style="max-width:100%;"></a></p>
     </div>
 

docs/how-to.md

@@ -274,7 +274,7 @@ That may work very well with static (or almost static) DBs, where there is not m
 
 Pagy is I18n ready. That means that all the UI strings that pagy uses are stored in a dictionaray YAML file, ready to be customized and/or translated/pluralized. The YAML file is available at `Pagy.root.join('locales', 'pagy.yml')`
 
-It contains a few entries used in the the UI by helpers and templates through the `pagy_t` method (eqivalent to the `I18n.t` or rails `t` helper). For more details, please take a look at the [pagy.yml file](https://github.com/ddnexus/pagy/blob/master/lib/locales/pagy.yml) and read the [pagy_t API documentation](api/frontend.md#pagy_tpath-vars)
+It contains a few entries used in the the UI by helpers and templates through the `pagy_t` method (eqivalent to the `I18n.t` or rails `t` helper). For more details, please take a look at the [pagy.yml dictionary file](https://github.com/ddnexus/pagy/blob/master/lib/locales/pagy.yml) and read the [pagy_t API documentation](api/frontend.md#pagy_tpath-vars)
 
 ## Using the pagy_info helper
 

docs/migration-tips.md

@@ -0,0 +1,130 @@
+---
+title: Migration Tips
+---
+
+# Migration Tips
+
+This page tries to cover most of the standard changes you will need to make in order to to migrate from a legacy pagination, however, if the legacy pagination is higly customized you may need more digging into the Pagy documentation. Feel free to ask on Gitter if you need more assistance:&nbsp;&nbsp;<a href="https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" rel="nofollow" target="_blank"><img src="https://camo.githubusercontent.com/1adf5e58915e2093fd2e856136ae26c99e2ae214/68747470733a2f2f6261646765732e6769747465722e696d2f727562792d706167792f4c6f6262792e737667" alt="Join the chat at https://gitter.im/ruby-pagy/Lobby" data-canonical-src="https://badges.gitter.im/ruby-pagy/Lobby.svg" style="max-width:100%;"></a>
+
+## Phases
+
+The Pagy API is quite different from other pagination gems, so there is not always a one-to-one correlation between the changes you will have to make, however, if you split the process in the following general phases it should be quite simple.
+
+1. Removing the egacy code trying to convert the statements that have a direct relation with Pagy
+2. Running the app so to raise exceptions in order to find legacy code that may be still in place
+3. When the app runs without error, adjusting the pagination to look and work as before
+
+### Removing the old code
+
+In this phase you will search statements from legacy pagination gems, remove them and possibly write the equivalent Pagy statements if that makes sense for Pagy:
+
+- If it makes sense, you should add the equivalent Pagy statement and remove the legacy statement(s).
+- If it doesn't make sense, then just remove the legacy statement.
+
+__Notice:__ Don't worry about missing something in this phase: if anything wont work as before you can fix it later in the process.
+
+#### Preparation
+
+- Create an empty Pagy initializer file: you will add to it during the process.
+- Add the `include Pagy::Backend` statement to the application controller.
+- Add the `include Pagy::Frontend` statement to the application helper.
+- Keep handy the legacy gem doc and the [Pagy API doc](api/pagy.md) in parallel.
+
+#### Application-wide search and replace
+
+Search for the class name of the pagination gem to migrate from, for example `WillPaginate` or `Kaminari`. You should find most of the code relative to global gem configuration, or monkey patching.
+
+For example, the following configuration are equivalent:
+
+```ruby
+WillPaginate.per_page = 10  
+WillPaginate::ViewHelpers.pagination_options[:inner_window] = 4
+WillPaginate::ViewHelpers.pagination_options[:outer_window] = 5
+```
+```ruby
+Kaminari.configure do |config|
+  config.max_per_page = 10
+  config.window = 4
+  config.outer_window = 5
+  #config.left = 0
+  #config.right = 0
+end  
+```
+```ruby
+Pagy::VARS[:items] = 10 
+Pagy::Vars[:size]  = [5,4,4,5]
+```
+
+#### Cleanup the Models
+
+One of the most noticeable difference between the legacy gems and Pagy is that Pagy doesn't mess at all with the models (read the reasons [here](index.md#stay-away-from-the-models)), while the other gems are careless about adding methods, scopes, and even configuration settings to them.
+
+So you should remove all the legacy code in the model and eventually add the equivalent code where it makes sense to Pagy, which _is absolutely not_ in the models.
+
+For example, you may want to search for keywords like `per_page`, `per` and such, which are actually configuration settings. They should either go into the Pagy initializer (if they are global to the app) or into the specific `pagy` call in the controller if they are specific to an action.
+
+If the app used the `page` scope in some of its methods or scopes, that should be removed (including removing the argument used to pass the page number to the scope), leaving the rest of the scope in place. Search where the app uses the already paginated scope in the controllers, and use the scope in a regular `pagy` statement. For example:
+
+```ruby
+#@records = Product.paginated_scope(params[:page])
+@pagy, @records = pagy(Product.non_paginated_scope)
+```
+
+#### Search and replace in the Controllers
+
+In the controllers, the occurency of statements from legacy pagination should have a one-to-one relationship with Pagy pagination, so you should be able to go through each of them and convert them quite easily.
+
+Search for keywords like `page` and `paginate` statements and use the `pagy` method instead. For example:
+
+```ruby
+#@records = Product.some_scope.page(params[:page]) 
+#@records = Product.paginate(:page => params[:page])    
+
+@pagy, @records = pagy(Product.some_scope)
+```
+```ruby
+#@records = Product.some_scope.page(params[:page]).per(15) 
+#@records = Product.some_scope.page(params[:page]).per_page(15)  
+#@records = Product.paginate(page: params[:page], per_page: 15) 
+
+@pagy, @records = pagy(Product.some_scope, items: 15)
+```
+
+#### Search and replace in the Views
+
+Also in the views, the occurency of statements from legacy pagination should have a one-to-one relationship with Pagy pagination, so you should be able to go through each of them and convert them quite easily.
+
+Search for keywords like `will_paginate` and `paginate` statement and use one of the `pagy_nav` methods. For example:
+
+```erb
+<%= will_paginate @records %>
+<%= paginate @records %>
+
+<%== pagy_nav @pagy %>
+```
+
+## Find the remaining code
+
+If the app has tests it's time to run them. If not, start the app and navigate through its pages.
+
+If anything of the old code is still in place you should get some exception. In that case, just remove the old code and retry until there will be no exception.
+
+## Fine tuning
+
+If the app is working and displays the pagination, it's time to adjust Pagy as you need.
+
+If the old pagination was using custom items (e.g. custom params, urls, links, html elements, etc.) it will likely not work without some possibly easy adjustment.
+
+Please take a look at the topics in the [how-to](how-to.md) documentation: that should cover most of your custom needs.
+
+#### CSSs
+
+If you used bootstrap the same CSSs should work seamlessly with `pagy_nav_bootstrap` or with any of the bootstrap templates. If the app didn't use bootstrap, you may need to rename some rule in your CSSs.
+
+#### I18n
+
+If the app uses `I18n` you should copy and paste the entries in the [pagy.yml dictionary file](https://github.com/ddnexus/pagy/blob/master/lib/locales/pagy.yml) to the dictionaries of your app, and translate them accordingly.
+
+#### Gain some more speed
+
+In case the app is a single language app (even not English) you can gain some extra performance if you explicitly exclude the use of the `I18n` gem. In that case you should set `Pagy::I18N[:gem] = false` in the initializer. See the Pagy::I18N [:gem doc](api/frontend.md#pagyi18ngem) for more details.

docs/pagy-extras.md

@@ -27,7 +27,7 @@ gem 'pagy-extras'
 
 ## Description
 
-This gem doesn't define any new module or class: it just re-opens the `Pagy` class and modules, adding the extra methods as it was part of the `pagy` gem. This neatly separates the core code from the optional extras, still keeping its usage as simple as it was part of the core gem.
+This gem doesn't define any new module or class: it just re-opens the `Pagy` class and modules, adding the extra methods as they were part of the `pagy` gem. This neatly separates the core code from the optional extras, still keeping its usage as simple as it were part of the core gem.
 
 ## Methods
 

docs/pagy-extras/bootstrap.md

@@ -8,6 +8,8 @@ This extra adds a nav helper compatible with the Bootstrap pagination.
 
 ## Synopsys
 
+See [pagy-extras](../pagy-extras.md) for general usage info.
+
 Render the navigation links in some view...
 with a fast helper:
 ```erb
@@ -23,10 +25,9 @@ or with a template:
 This extra is composed of 4 files:
 
 - [bootstrap.rb](https://github.com/ddnexus/pagy-extras/blob/master/lib/pagy-extras/bootstrap.rb)
-- [nav_bootstrap.html.erb](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.erb)
-- [nav_bootstrap.html.haml](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.haml)
-- [nav_bootstrap.html.slim](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.slim)
-
+- [nav_bootstrap.html.erb](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.erb) (optional template)
+- [nav_bootstrap.html.haml](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.haml) (optional template)
+- [nav_bootstrap.html.slim](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.slim)  (optional template)
 
 ## Methods
 
@@ -38,4 +39,6 @@ This method is the same as the `pagy_nav`, but customized for Bootstrap.
 
 The `nav_bootstrap.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it.
 
-See also [Using Templates](../how-to.md#using-templates).
+### Optional Template Files
+
+See [Using Templates](../how-to.md#using-templates).

docs/pagy-extras/compact.md

@@ -13,6 +13,8 @@ Here is an example (bootstrap style):
 
 ## Synopsys
 
+See [pagy-extras](../pagy-extras.md) for general usage info.
+
 In an initializer file:
 
 ```ruby

docs/pagy-extras/responsive.md

@@ -12,6 +12,8 @@ Here is an example of how the same pagination nav might look like by resizing th
 
 ## Synopsys
 
+See [pagy-extras](../pagy-extras.md) for general usage info.
+
 ```ruby
 # set your default custom breakpoints (width/size pairs) globally (it can be overridden per pagy instance)
 Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]}