Documentation updates

ddnexus · Jun 9, 2018 · d4b751c · d4b751c
1 parent 9f0dec9
commit d4b751c
Show file tree

Hide file tree

Showing 11 changed files with 36 additions and 22 deletions.
diff --git a/README.md b/README.md
@@ -92,10 +92,8 @@ On resize, the number of page links will adapt in real-time to the available win
 
 An alternative UI that combines the pagination feature with the navigation info in one compact element. _(see [more...](http://ddnexus.github.io/pagy/extras/compact))_
 
-
 ![pagy-compact](docs/assets/images/pagy-compact-w.png)
 
-
 ### Array Extra
 
 Paginate arrays efficiently avoiding expensive array-wrapping and without any overriding. _(see [more...](http://ddnexus.github.io/pagy/extras/array))_
@@ -108,21 +106,27 @@ Paginate arrays efficiently avoiding expensive array-wrapping and without any ov
 
 - [Quick Start](https://ddnexus.github.io/pagy/how-to#quick-start)
 - [Documentation](https://ddnexus.github.io/pagy/index)
+- [Migrating from WillPaginate and Kaminari](https://ddnexus.github.io/pagy/migration-tips)
 - [Changelog](https://github.com/ddnexus/pagy/blob/master/CHANGELOG.md)
 - [Contributors](https://github.com/ddnexus/pagy/graphs/contributors)
 ---
 - [Detailed Gems Comparison](https://ddnexus.github.io/pagination-comparison/gems.html)
 - [Benchmarks and Memory Profiles Source](http://github.com/ddnexus/pagination-comparison)
 
+## Please Star and Share!
+
+Pagy is young and needs to be known.
+
+**You** can really help, even with just a click. Thank you!
+
 ## Help Wanted
 
 Pagy is a fresh project and your help would be great. If you like it, you have a few options to contribute:
 
-- Write a tutorial or a post or even just a tweet (Pagy is young and needs to be known)
-- Write a "How To" topic (the documentation is covering the basics and there is a lot of space for additions)
-- Submit some cool extra
-- 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
+- Submit a pull request to improve Pagy
+- Write a Tutorial or a "How To" topic
+- Submit some cool extra
 
 ## Branches and Pull Requests
 

diff --git a/docs/api.md b/docs/api.md
@@ -14,3 +14,5 @@ The whole core structure of Pagy is very simple: it is organized around 3 small
 | `Pagy::Frontend` | The module to include in your views in order to get a few helpers for the HTML output                           | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/frontend.rb), [documentation](api/frontend.md) |
 
 However, besides these files, you can explicitly require optional [extras](extras.md) that can handle special features, collections or environments.
+
+See also: [Global Configuration](how-to.md#global-configuration)
diff --git a/docs/api/frontend.md b/docs/api/frontend.md
@@ -118,7 +118,7 @@ If you need to add some HTML attribute to the page links, you can pass some extr
 
 1. For all pagy objects: set the global variable `:link_extra`:
     ```ruby
-    # in an initializer file
+    # in the Pagy initializer file
     Pagy::VARS[:link_extra] = 'data-remote="true"'
     # in any view
     link = pagy_link_proc(pagy)
@@ -172,7 +172,7 @@ The `Pagy::Frontend::I18N` constant is the core of the Pagy I18n implementation.
 
 #### Pagy::Frontend::I18N.load_file(file)
 
-This method allow to load a custom dictionary file, different from `Pagy.root.join('locales', 'pagy.yml')`. If the `i18n` extra is used it has no effect. It is tipically used in the initializer file. For example:
+This method allow to load a custom dictionary file, different from `Pagy.root.join('locales', 'pagy.yml')`. If the `i18n` extra is used it has no effect. It is tipically used in the Pagy initializer file _(see [Configuration](../how-to.md#global-configuration))_. For example:
 
 ```ruby
 Pagy::Frontend::I18N.load_file('path/to/dictionary.yml')

diff --git a/docs/api/pagy.md b/docs/api/pagy.md
@@ -8,7 +8,7 @@ The scope of the `Pagy` class is keeping track of the all integers and variables
 ## Synopsys
 
 ```ruby
-# set global defaults and extra variables typically in an initializer
+# set global defaults and extra variables typically in the Pagy initializer
 # they will get merged with every new Pagy instance
 Pagy::VARS[:items]    = 25
 Pagy::VARS[:some_var] = 'default value'

diff --git a/docs/extras.md b/docs/extras.md
@@ -6,16 +6,16 @@ title: Extras
 Pagy comes with a few optional extensions/extras:
 
 | Extra        | Description                                                                                            | Links                                                                                                                                                                                                                                               |
-|-------------|-------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|--------------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `array`      | Paginate arrays efficiently avoiding expensive array-wrapping and wihout overriding                    | [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb), [documentation](extras/array.md)                                                                                                                                  |
 | `bootstrap`  | Nav helper and templates for Bootstrap pagination                                                      | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md)                                                                                                                      |
-| `compact`    | An alternative UI that combines the pagination  with the nav info in a single compact element               | [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/compact.rb), [pagy-compact.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy-compact.js), [documentation](extras/compact.md)                |
-| `i18n`       | Uses the `I18n` gem instead of the pagy implementation                                                 | [i18n.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/i81n.rb), [documentation](extras/i18n.md)                                                                                                                                     |
+| `compact`    | An alternative UI that combines the pagination  with the nav info in a single compact element          | [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/compact.rb), [pagy-compact.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy-compact.js), [documentation](extras/compact.md)                |
+| `i18n`       | Use the `I18n` gem instead of the pagy implementation                                                  | [i18n.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/i81n.rb), [documentation](extras/i18n.md)                                                                                                                                     |
 | `responsive` | On resize, the number of page links will adapt in real-time to the available window or container width | [responsive.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/responsive.rb), [pagy-responsive.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy-responsive.js), [documentation](extras/responsive.md) |
 
 ## Synopsys
 
-Extras are not loaded by default, so you should require them explicitly in your initializer:
+Extras are not loaded by default, so you should require them explicitly in your initializer _(see [Configuration](how-to.md#global-configuration))_:
 
 ```ruby
 require 'pagy/extras/bootstrap'

diff --git a/docs/extras/compact.md b/docs/extras/compact.md
@@ -15,7 +15,7 @@ Here is an example (bootstrap style):
 
 See [extras](../extras.md) for general usage info.
 
-In an initializer file:
+In the Pagy initializer file:
 
 ```ruby
 # in rails apps: add the assets-path

diff --git a/docs/extras/i18n.md b/docs/extras/i18n.md
@@ -3,7 +3,7 @@ title: I18n
 ---
 # I18n Extra
 
-The `I18n` extra overrides the `pagy_t` method so it uses `I18n.t`. Use this extra only with multi-language apps since the `I18n` gem adds quite an overhead and slowers down Pagy.
+The `i18n` extra overrides the `pagy_t` method so it uses `I18n.t`. Use this extra only with multi-language apps since the `I18n` gem adds quite an overhead and slowers down Pagy.
 
 See also [I18n](../api/frontend.md#i18n).
 
@@ -12,6 +12,12 @@ See also [I18n](../api/frontend.md#i18n).
 See [extras](../extras.md) for general usage info.
 
 ```ruby
-# in the initializer
+# in the Pagy initializer
 require 'pagy/extra/i18n'
 ```
+
+## Files
+
+This extra is composed of 1 small file:
+
+- [i18n.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/i18n.rb)
diff --git a/docs/extras/responsive.md b/docs/extras/responsive.md
@@ -14,7 +14,7 @@ Here is an example of how the same pagination nav might look like by resizing th
 See [extras](../extras.md) for general usage info.
 
 ```ruby
-# in the initializer
+# in the Pagy initializer
 require 'pagy/extra/responsive'
 
 # set your default custom breakpoints (width/size pairs) globally (it can be overridden per Pagy instance)

diff --git a/docs/how-to.md b/docs/how-to.md
@@ -56,7 +56,9 @@ or with a template:
 
 ## Global Configuration
 
-Pagy should work out of the box for most Rack based apps (e.g. Rails) even without configuring anything, however you can configure all its features by creating a `pagy.rb` initializer file, copying the content of the [initializer_example.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/initializer_example.rb) and uncomment and edit what you may need.
+Pagy should work out of the box for most Rack based apps (e.g. Rails) even without configuring anything, however you can configure all its features and all the extras loading a `pagy.rb` initializer file.
+
+You can copy the comprehensive and annotated content of the [initializer_example.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/initializer_example.rb) and uncomment and edit what you may need. The file contains also all the relevant documentation links.
 
 ## Environment Assumptions
 
@@ -85,7 +87,7 @@ Pagy can work in any other scenario assuming that:
 
 You can control the items per page with the `items` variable. (Default `20`)
 
-You can set its default in the `pagy.rb` initializer. For example:
+You can set its default in the `pagy.rb` initializer _(see [Configuration](#global-configuration)_. For example:
 
 ```ruby
 Pagy::VARS[:items] = 25

diff --git a/docs/migration-tips.md b/docs/migration-tips.md
@@ -1,7 +1,7 @@
 ---
 title: Migration Tips
 ---
-# Migration Tips
+# Migrating from WillPaginate and Kaminari
 
 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.
 
@@ -60,7 +60,7 @@ Pagy::VARS[:items] = 10
 Pagy::Vars[:size]  = [5,4,4,5]
 ```
 
-Remove all the old settings and uncomment and edit the new settings in the `pagy.rb` initializer.
+Remove all the old settings and uncomment and edit the new settings in the `pagy.rb` initializer _(see [Configuration](how-to.md#global-configuration))_.
 
 #### Cleanup the Models
 

diff --git a/lib/pagy/extras/initializer_example.rb b/lib/pagy/extras/initializer_example.rb
@@ -17,7 +17,7 @@
 # See https://ddnexus.github.io/pagy/extras/compact
 # require 'pagy/extras/compact'
 
-# I18n: Uses the `I18n` gem instead of the pagy implementation
+# I18n: Use the `I18n` gem instead of the pagy implementation
 # See https://ddnexus.github.io/pagy/extras/i18n
 # require 'pagy/extras/i18n'