Improve docs

README.md

@@ -162,7 +162,7 @@ end
 Some formatting options are also available.
 Each column is sortable.
 
-[More about columns](https://github.com/bogdan/datagrid/wiki/Columns)
+[More about columns](https://rubydoc.info/gems/datagrid/Datagrid/Columns)
 
 ### Front end
 

datagrid.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |s|
   s.metadata = {
     "homepage_uri" => s.homepage,
     "bug_tracker_uri" => "#{s.homepage}/issues",
-    "documentation_uri" => "#{s.homepage}/wiki",
+    "documentation_uri" => "https://rubydoc.info/gems/datagrid",
     "changelog_uri" => "#{s.homepage}/blob/main/CHANGELOG.md",
     "source_code_uri" => s.homepage,
     "rubygems_mfa_required" => "true",

lib/datagrid/columns.rb

@@ -2,6 +2,7 @@
 
 require "datagrid/utils"
 require "active_support/core_ext/class/attribute"
+require "datagrid/columns/column"
 
 module Datagrid
   # Defines a column to be used for displaying data in a Datagrid.
@@ -199,29 +200,26 @@ module Datagrid
   #       presenter.user.created_at
   #     end
   module Columns
-    require "datagrid/columns/column"
-
-    # @!method default_column_options=(value)
-    # @param [Hash] value default options passed to #column method call
-    # @return [Hash] default options passed to #column method call
-    # @example
-    #   # Disable default order
+    # @param [Hash] value default options passed to {#column} method call
+    # @return [Hash] default options passed to {#column} method call
+    # @example Disable default order
     #   self.default_column_options = { order: false }
-    #   # Makes entire report HTML
+    # @example Makes entire report HTML
     #   self.default_column_options = { html: true }
+    # @!method default_column_options=(value)
 
-    # @!method default_column_options
-    # @return [Hash]
+    # @return [Hash] default options passed to {#column} method call
     # @see #default_column_options=
+    # @!method default_column_options
 
     # @!method batch_size=(value)
-    # @param [Integer] value Specify a default batch size when generating CSV or just data. Default: 1000
-    # @return [Integer] Specify a default batch size when generating CSV or just data.
-    # @example
+    # Specify a default batch size when generating CSV or just data.
+    # @param [Integer] value a batch size when generating CSV or just data. Default: 1000
+    # @return [void]
+    # @example Set batch size to 500
     #   self.batch_size = 500
-    #   # Disable batches
+    # @example Disable batches
     #   self.batch_size = nil
-    #
 
     # @!method batch_size
     # @return [Integer]
@@ -253,37 +251,31 @@ def columns(*column_names, data: false, html: false)
         filter_columns(columns_array, *column_names, data: data, html: html)
       end
 
-      # Defines new datagrid column
-      #
+      # Defines a new datagrid column
       # @param name [Symbol] column name
       # @param query [String, nil] a string representing the query to select this column (supports only ActiveRecord)
-      # @param options [Hash{Symbol => Object}] hash of options
       # @param block [Block] proc to calculate a column value
+      # @option options [Boolean, String] html Determines if the column should be present
+      #   in the HTML table and how it is formatted.
+      # @option options [String, Array<Symbol>] order Determines if the column can be sortable and
+      #   specifies the ORM ordering method.
+      #   Example: `"created_at, id"` for ActiveRecord, `[:created_at, :id]` for Mongoid.
+      # @option options [String] order_desc Specifies a descending order for the column
+      #   (used when `:order` cannot be easily reversed by the ORM).
+      # @option options [Boolean, Proc] order_by_value Enables Ruby-level ordering for the column.
+      #   Warning: Sorting large datasets in Ruby is not recommended.
+      #   If `true`, Datagrid orders by the column value.
+      #   If a block is provided, Datagrid orders by the block's return value.
+      # @option options [Boolean] mandatory If `true`, the column will never be hidden by the `#column_names` selection.
+      # @option options [Symbol] before Places the column before the specified column when determining order.
+      # @option options [Symbol] after Places the column after the specified column when determining order.
+      # @option options [Boolean, Proc] if conditions when a column is available.
+      # @option options [Boolean, Proc] unless conditions when a column is not available.
+      # @option options [Symbol, Array<Symbol>] preload Specifies associations
+      #   to preload for the column within the scope.
+      # @option options [Hash] tag_options Specifies HTML attributes for the `<td>` or `<th>` of the column.
+      #   Example: `{ class: "content-align-right", "data-group": "statistics" }`.
       # @return [Datagrid::Columns::Column]
-      #
-      # Available options:
-      #
-      # * <tt>html</tt> - determines if current column should be present in html table and how is it formatted
-      # * <tt>order</tt> - determines if this column could be sortable and how.
-      #   The value of order is explicitly passed to ORM ordering method.
-      #   Example: <tt>"created_at, id"</tt> for ActiveRecord, <tt>[:created_at, :id]</tt> for Mongoid
-      # * <tt>order_desc</tt> - determines a descending order for given column
-      #   (only in case when <tt>:order</tt> can not be easily reversed by ORM)
-      # * <tt>order_by_value</tt> - used in case it is easier to perform ordering at ruby level not on database level.
-      #   Warning: using ruby to order large datasets is very unrecommended.
-      #   If set to true - datagrid will use column value to order by this column
-      #   If block is given - datagrid will use value returned from block
-      # * <tt>mandatory</tt> - if true, column will never be hidden with #column_names selection
-      # * <tt>url</tt> - a proc with one argument, pass this option to easily convert the value into an URL
-      # * <tt>before</tt> - determines the position of this column, by adding it before the column passed here
-      # * <tt>after</tt> - determines the position of this column, by adding it after the column passed here
-      # * <tt>if</tt> - the column is shown if the reult of calling this argument is true
-      # * <tt>unless</tt> - the column is shown unless the reult of calling this argument is true
-      # * <tt>preload</tt> - spefies which associations of the scope should be preloaded for this column
-      # * `tag_options` - specify HTML attributes to be set for `<td>` or `<th>` of a column
-      #   Example: `{ class: "content-align-right", "data-group": "statistics" }`
-      #
-      # @see https://github.com/bogdan/datagrid/wiki/Columns
       def column(name, query = nil, **options, &block)
         define_column(columns_array, name, query, **options, &block)
       end
@@ -333,10 +325,10 @@ def format(value, &block)
       # Defines a model decorator that will be used to define a column value.
       # All column blocks will be given a decorated version of the model.
       # @return [void]
-      # @example
+      # @example Wrapping a model with presenter
       #   decorate { |user| UserPresenter.new(user) }
-      #
-      #   decorate { UserPresenter } # a shortcut
+      # @example A shortcut for doing the same
+      #   decorate { UserPresenter }
       def decorate(model = nil, &block)
         if !model && !block
           raise ArgumentError, "decorate needs either a block to define decoration or a model to decorate"
@@ -403,14 +395,16 @@ def assets
       )
     end
 
-    # @param column_names [Array<String, Symbol>] list of column names if you want to limit data only to specified columns
+    # @param column_names [Array<String, Symbol>] list of column names
+    #   if you want to limit data only to specified columns
     # @return [Array<String>] human readable column names. See also "Localization" section
     def header(*column_names)
       data_columns(*column_names).map(&:header)
     end
 
     # @param asset [Object] asset from datagrid scope
-    # @param column_names [Array<String, Symbol>] list of column names if you want to limit data only to specified columns
+    # @param column_names [Array<String, Symbol>] list of column names
+    #   if you want to limit data only to specified columns
     # @return [Array<Object>] column values for given asset
     def row_for(asset, *column_names)
       data_columns(*column_names).map do |column|
@@ -419,7 +413,8 @@ def row_for(asset, *column_names)
     end
 
     # @param asset [Object] asset from datagrid scope
-    # @return [Hash] A mapping where keys are column names and values are column values for the given asset
+    # @return [Hash] A mapping where keys are column names and
+    #   values are column values for the given asset
     def hash_for(asset)
       result = {}
       data_columns.each do |column|
@@ -428,15 +423,17 @@ def hash_for(asset)
       result
     end
 
-    # @param column_names [Array<String,Symbol>] list of column names if you want to limit data only to specified columns
+    # @param column_names [Array<String,Symbol>] list of column names
+    #   if you want to limit data only to specified columns
     # @return [Array<Array<Object>>] with data for each row in datagrid assets without header
     def rows(*column_names)
       map_with_batches do |asset|
         row_for(asset, *column_names)
       end
     end
 
-    # @param column_names [Array<String, Symbol>] list of column names if you want to limit data only to specified columns
+    # @param column_names [Array<String, Symbol>] list of column names
+    #   if you want to limit data only to specified columns.
     # @return [Array<Array<Object>>] data for each row in datagrid assets with header.
     def data(*column_names)
       rows(*column_names).unshift(header(*column_names))
@@ -514,25 +511,24 @@ def html_columns(*column_names, data: false)
       columns(*column_names, data: data, html: true)
     end
 
-    # Finds a column definition by name
+    # Finds a column by name
     # @param name [String, Symbol] column name to be found
     # @return [Datagrid::Columns::Column, nil]
     def column_by_name(name)
       self.class.find_column_by_name(columns_array, name)
     end
 
     # Gives ability to have a different formatting for CSV and HTML column value.
-    #
-    # @example
+    # @example Formating using Rails view helpers
     #   column(:name) do |model|
     #     format(model.name) do |value|
     #       tag.strong(value)
     #     end
     #   end
-    #
+    # @example Formatting using a separated view template
     #   column(:company) do |model|
     #     format(model.company.name) do
-    #       render partial: "company_with_logo", locals: {company: model.company }
+    #       render partial: "companies/company_with_logo", locals: {company: model.company }
     #     end
     #   end
     # @return [Datagrid::Columns::Column::ResponseFormat] Format object
@@ -548,18 +544,18 @@ def format(value, &block)
     # @param [Object] asset one of the assets from grid scope
     # @return [Datagrid::Columns::DataRow] an object representing a grid row.
     # @example
-    #  class MyGrid
-    #    scope { User }
-    #    column(:id)
-    #    column(:name)
-    #    column(:number_of_purchases) do |user|
-    #      user.purchases.count
-    #    end
-    #  end
+    #   class MyGrid
+    #     scope { User }
+    #     column(:id)
+    #     column(:name)
+    #     column(:number_of_purchases) do |user|
+    #       user.purchases.count
+    #     end
+    #   end
     #
-    #  row = MyGrid.new.data_row(User.last)
-    #  row.id # => user.id
-    #  row.number_of_purchases # => user.purchases.count
+    #   row = MyGrid.new.data_row(User.last)
+    #   row.id # => user.id
+    #   row.number_of_purchases # => user.purchases.count
     def data_row(asset)
       ::Datagrid::Columns::DataRow.new(self, asset)
     end

lib/datagrid/configuration.rb

@@ -25,12 +25,14 @@ def self.configure(&block)
   # Datagrid.configure do |config|
   #   # Defines date formats that can be used to parse dates.
   #   # Note: Multiple formats can be specified. The first format is used to format dates as strings,
-  #   # while other formats are used only for parsing dates from strings (e.g., if your app supports multiple formats).
+  #   # while other formats are used only for parsing dates
+  #   # from strings (e.g., if your app supports multiple formats).
   #   config.date_formats = "%m/%d/%Y", "%Y-%m-%d"
   #
   #   # Defines timestamp formats that can be used to parse timestamps.
   #   # Note: Multiple formats can be specified. The first format is used to format timestamps as strings,
-  #   # while other formats are used only for parsing timestamps from strings (e.g., if your app supports multiple formats).
+  #   # while other formats are used only for parsing timestamps
+  #   # from strings (e.g., if your app supports multiple formats).
   #   config.datetime_formats = ["%m/%d/%Y %h:%M", "%Y-%m-%d %h:%M:%s"]
   # end
   # ```

lib/datagrid/filters.rb

@@ -204,8 +204,8 @@ def filter_by_name(attribute)
       #   Used with the `datagrid_form_for` helper.
       # @option options [Symbol] after Specifies the position of this filter by placing it after another filter.
       #   Used with the `datagrid_form_for` helper.
-      # @option options [Boolean] dummy If true, the filter is not applied automatically and is only displayed in the form.
-      #   Useful for manual application.
+      # @option options [Boolean] dummy If true, the filter is not applied automatically and
+      #   is only displayed in the form. Useful for manual application.
       # @option options [Proc, Symbol] if Specifies a condition under which the filter is displayed and used.
       #   Accepts a block or the name of an instance method.
       # @option options [Proc, Symbol] unless Specifies a condition under which the filter is NOT displayed or used.

lib/datagrid/helper.rb

@@ -17,7 +17,8 @@ module Datagrid
   # [built-in CSS](https://github.com/bogdan/datagrid/blob/master/app/assets/stylesheets/datagrid.sass).
   #
   # Datagrid includes helpers and a form builder for easy frontend generation.
-  # If you need a fully-featured custom GUI, create your templates manually with the help of the {Datagrid::Columns} API.
+  # If you need a fully-featured custom GUI, create your templates manually
+  # with the help of the {Datagrid::Columns} API.
   #
   # ## Controller and Routing
   #
@@ -63,7 +64,8 @@ module Datagrid
   #
   # ### Advanced Method
   #
-  # You can use Rails built-in tools to create a form. Additionally, Datagrid provides helpers to generate input/select elements for filters:
+  # You can use Rails built-in tools to create a form.
+  # Additionally, Datagrid provides helpers to generate input/select elements for filters:
   #
   # ``` haml
   # - form_with model: UserGrid.new, method: :get, url: users_path do |f|
@@ -360,9 +362,8 @@ def datagrid_order_for(grid, column, options = {})
     # @option options [String] partials Path for form partial lookup.
     #   Default: `'datagrid'`, which uses `app/views/datagrid/` partials.
     #   Example: `'datagrid_admin'` uses `app/views/datagrid_admin` partials.
-    # @option options [Object] model The Datagrid object to be rendered.
+    # @option options [Datagrid::Base] model a Datagrid object to be rendered.
     # @option options [Hash] All options supported by Rails `form_with` helper.
-    # @param grid [Datagrid::Base] grid object
     # @param [Hash{Symbol => Object}] options
     # @return [String] form HTML tag markup
     def datagrid_form_with(**options)
@@ -466,7 +467,7 @@ def _render_partial(partial_name, partials_path, locals = {})
     #   row = datagrid_row(grid, user)
     #   row.class      # => Datagrid::Helper::HtmlRow
     #   row.first_name # => "<strong>Bogdan</strong>"
-    #   row.grid       # => Grid object
+    #   row.grid       # => Datagrid::Base object
     #   row.asset      # => User object
     #   row.each do |value|
     #     puts value

version-2/Readme.markdown

@@ -63,8 +63,6 @@ Rails [deprecates form\_for in favor of form\_with](https://guides.rubyonrails.o
 
 `datagrid_form_for` is now deprecated if favor of `datagrid_form_with`.
 
-TODO: update the wiki
-
 ``` ruby
 # V1
 datagrid_form_for(@users_grid, url: users_path)
@@ -184,7 +182,7 @@ and avoid collisions with other libraries:
 | checkboxes   | datagrid-enum-checkboxes            |
 
 All classes are now explicitly assinged inside datagrid partials.
-[Modify built-in partials](https://github.com/bogdan/datagrid/wiki/Frontend#modifying-built-in-partials)
+[Modify built-in partials](https://rubydoc.info/gems/datagrid/Datagrid/Helper#modifying-built-in-partials)
 if you want to change them.
 
 Diff for [built-in partials between V1 and V2](./views.diff)
@@ -370,7 +368,7 @@ instead of classes for column names.
 * Column name `th[class], td[class]` implemented as `td[data-column], th[data-column]`.
 
 Note that the behavior change can be reverted by 
-[updating built-in partials](https://github.com/bogdan/datagrid/wiki/Frontend#modifying-built-in-partials).
+[Modify built-in partials](https://rubydoc.info/gems/datagrid/Datagrid/Helper#modifying-built-in-partials)
 Version 2 makes it as easy as possible to override the defaults of the UI.
 
 ### Filters
@@ -451,7 +449,7 @@ Renders:
 <td class="short-column" data-column="name">John</td>
 ```
 
-[Modify built-in views](https://github.com/bogdan/datagrid/wiki/Frontend#modifying-built-in-partials)
+[Modify built-in partials](https://rubydoc.info/gems/datagrid/Datagrid/Helper#modifying-built-in-partials)
 if you want to change this behavior completely.
 
 ## Use column[tag\_options]