Documentation updates for release v1.7

CONTRIBUTING.md

@@ -1,7 +1,15 @@
 ## Contributing
 
-First off, thank you for considering contributing to Active Admin. It's people
-like you that make Active Admin such a great tool.
+This is probably not a beginner friendly project: it has a long history, complex functionality, 
+and too much cleverness, eg. metaprogramming.
+
+If you are using, or intending to use this project in production it would be great to hear about that in the discussions area.
+Fixes are welcome, if you have ideas for improvements reach out to the maintainer first.
+
+Translations and documentation tweaks are welcome, but not a priority, don't expect a quick response.
+
+Linting has become very popular in recent years, eg. rubocop, but depending on the team or project it can quickly
+become a couterproductive distraction.  By all means make suggestions, but don't expect a quick response.
 
 ### 1. Where do I go from here?
 
@@ -23,13 +31,12 @@ git checkout -b 325-add-japanese-translations
 
 ### 3. Get the test suite running
 
-Make sure you're using a recent ruby and have the `bundler` gem installed, at
-least version `1.14.3`.
+Make sure you're using a recent ruby and have the `bundler` gem installed.
 
 Select the Gemfile for your preferred Rails version, preferably the latest:
 
 ```sh
-export BUNDLE_GEMFILE=gemfiles/rails_51.gemfile
+export BUNDLE_GEMFILE=gemfiles/rails_71.gemfile
 ```
 
 Now install the development dependencies:
@@ -47,7 +54,7 @@ bundle exec rake
 The test run will generate a sample Rails application in `spec/rails` to run the
 tests against.
 
-If your tests are passing locally but they're failing on Travis, reset your test
+If your tests are passing locally but they're failing on GitHub, reset your test
 environment:
 
 ```sh
@@ -68,12 +75,11 @@ rm -rf spec/rails && bundle update
   Simply copy the content of the appropriate template into a .rb file, make the
   necessary changes to demonstrate the issue, and **paste the content into the
   issue description**:
-  * [**ActiveAdmin** master issues][master template]
+  * [**ActiveAdmin** main issues][main template]
 
 ### 5. Implement your fix or feature
 
-At this point, you're ready to make your changes! Feel free to ask for help;
-everyone is a beginner at first :smile_cat:
+At this point, you're ready to make your changes! Feel free to ask for help.
 
 ### 6. View your changes in a Rails application
 
@@ -117,20 +123,20 @@ it locally using [Codeclimate's CLI][codeclimate cli], via `codeclimate analyze`
 
 ### 8. Make a Pull Request
 
-At this point, you should switch back to your master branch and make sure it's
-up to date with Active Admin's master branch:
+At this point, you should switch back to your main branch and make sure it's
+up to date with Active Admin's main branch:
 
 ```sh
 git remote add upstream [email protected]:activeadmin/activeadmin.git
-git checkout master
-git pull upstream master
+git checkout main
+git pull upstream main
 ```
 
-Then update your feature branch from your local copy of master, and push it!
+Then update your feature branch from your local copy of main, and push it!
 
 ```sh
 git checkout 325-add-japanese-translations
-git rebase master
+git rebase main
 git push --set-upstream origin 325-add-japanese-translations
 ```
 
@@ -153,19 +159,19 @@ To learn more about rebasing in Git, there are a lot of [good][git rebasing]
 
 ```sh
 git checkout 325-add-japanese-translations
-git pull --rebase upstream master
+git pull --rebase upstream main
 git push --force-with-lease 325-add-japanese-translations
 ```
 
 ### 10. Merging a PR (maintainers only)
 
-A PR can only be merged into master by a maintainer if:
+A PR can only be merged into main by a maintainer if:
 
 * It is passing CI.
 * It has been approved by at least two maintainers. If it was a maintainer who
   opened the PR, only one extra approval is needed.
 * It has no requested changes.
-* It is up to date with current master.
+* It is up to date with current main.
 
 Any maintainer is allowed to merge a PR if all of these conditions are
 met.
@@ -176,7 +182,7 @@ met.
 [new issue]: https://github.com/activeadmin/activeadmin/issues/new
 [fork Active Admin]: https://help.github.com/articles/fork-a-repo
 [searching all issues]: https://github.com/activeadmin/activeadmin/issues?q=
-[master template]: https://github.com/activeadmin/activeadmin/blob/master/lib/bug_report_templates/active_admin_master.rb
+[main template]: https://github.com/varyonic/activeadmin/blob/main/lib/bug_report_templates/active_admin_main.rb
 [codeclimate]: https://codeclimate.com
 [codeclimate cli]: https://github.com/codeclimate/codeclimate
 [make a pull request]: https://help.github.com/articles/creating-a-pull-request

README.md

@@ -43,14 +43,14 @@ We try not to reinvent the wheel, so Active Admin is built with other open sourc
 
 Tool                  | Description
 --------------------- | -----------
-[Arbre]               | Ruby -> HTML, just like that.
+[Arbo]                | HTML Views in Ruby.
 [Devise]              | Powerful, extensible user authentication
 [Formtastic]          | A Rails form builder plugin with semantically rich and accessible markup
 [Inherited Resources] | Simplifies controllers with pre-built RESTful controller actions
 [Kaminari]            | Elegant pagination for any sort of collection
 [Ransack]             | Provides a simple search API to query your data
 
-[Arbre]: https://github.com/activeadmin/arbre
+[Arbo]: https://github.com/varyonic/arbo
 [Devise]: https://github.com/plataformatec/devise
 [Formtastic]: https://github.com/justinfrench/formtastic
 [Inherited Resources]: https://github.com/activeadmin/inherited_resources
@@ -61,15 +61,15 @@ Tool                  | Description
 [rubygems]: https://rubygems.org/gems/activeadmin-rb
 [actions_badge]: https://github.com/varyonic/activeadmin/workflows/ci/badge.svg
 [actions]: https://github.com/varyonic/activeadmin/actions
-[codeclimate_badge]: https://api.codeclimate.com/v1/badges/779e407d22bacff19733/maintainability
+[codeclimate_badge]: https://api.codeclimate.com/v1/badges/1698787497cc7d4c7c88/maintainability
 [codeclimate]: https://codeclimate.com/github/varyonic/activeadmin/maintainability
-[codecov_badge]: https://codecov.io/gh/varyonic/activeadmin/branch/master/graph/badge.svg
+[codecov_badge]: https://codecov.io/gh/varyonic/activeadmin/branch/main/graph/badge.svg
 [codecov]: https://codecov.io/gh/varyonic/activeadmin
-[inch_badge]: http://inch-ci.org/github/varyonic/activeadmin.svg?branch=master
+[inch_badge]: http://inch-ci.org/github/varyonic/activeadmin.svg?branch=main
 [inch]: http://inch-ci.org/github/varyonic/activeadmin
 
 [docs]: http://activeadmin.info/0-installation.html
 [demo]: http://demo.activeadmin.info/admin
 [wiki]: https://github.com/varyonic/activeadmin/wiki
 [stackoverflow]: http://stackoverflow.com/questions/tagged/activeadmin
-[contributing]: https://github.com/varyonic/activeadmin/blob/master/CONTRIBUTING.md
+[contributing]: https://github.com/varyonic/activeadmin/blob/main/CONTRIBUTING.md

docs/0-installation.md

@@ -1,4 +1,7 @@
 ---
+layout: default
+nav_order: 0
+title: Installation
 redirect_from: /docs/0-installation.html
 ---
 
@@ -7,7 +10,7 @@ redirect_from: /docs/0-installation.html
 Active Admin is a Ruby Gem.
 
 ```ruby
-gem 'activeadmin'
+gem 'activeadmin-rb'
 
 # Plus integrations with:
 gem 'devise'
@@ -112,7 +115,7 @@ Draper::CollectionDecorator.send :delegate, :per_page_kaminari
 
 If you're getting the error `wrong number of arguments (6 for 4..5)`, [read #2703].
 
-[CHANGELOG]: https://github.com/activeadmin/activeadmin/blob/master/CHANGELOG.md
-[dashboard.rb]: https://github.com/activeadmin/activeadmin/blob/master/lib/generators/active_admin/install/templates/dashboard.rb
-[active_admin.rb]: https://github.com/activeadmin/activeadmin/blob/master/lib/generators/active_admin/install/templates/active_admin.rb.erb
+[CHANGELOG]: https://github.com/varyonic/activeadmin/blob/main/CHANGELOG.md
+[dashboard.rb]: https://github.com/varyonic/activeadmin/blob/main/lib/generators/active_admin/install/templates/dashboard.rb
+[active_admin.rb]: https://github.com/varyonic/activeadmin/blob/main/lib/generators/active_admin/install/templates/active_admin.rb.erb
 [read #2703]: https://github.com/activeadmin/activeadmin/issues/2703#issuecomment-38140864

docs/1-general-configuration.md

@@ -1,4 +1,7 @@
 ---
+layout: default
+nav_order: 1
+title: General Configuration
 redirect_from: /docs/1-general-configuration.html
 ---
 
@@ -47,17 +50,17 @@ config.site_title_image = ->(context) { context.current_user.company.logo_url }
 ## Internationalization (I18n)
 
 Active Admin comes with translations for a lot of
-[locales](https://github.com/activeadmin/activeadmin/blob/master/config/locales/).
+[locales](https://github.com/varyonic/activeadmin/blob/main/config/locales/).
 Active Admin does not provide the translations for the kaminari gem it uses for pagination,
 to get these you can use the
 [kaminari-i18n](https://github.com/tigrish/kaminari-i18n) gem.
 
 To translate Active Admin to a new language or customize an existing
 translation, you can copy
-[config/locales/en.yml](https://github.com/activeadmin/activeadmin/blob/master/config/locales/en.yml)
+[config/locales/en.yml](https://github.com/varyonic/activeadmin/blob/main/config/locales/en.yml)
 to your application's `config/locales` folder and update it. We welcome
 new/updated translations, so feel free to
-[contribute](https://github.com/activeadmin/activeadmin/blob/master/CONTRIBUTING.md)!
+[contribute](https://github.com/varyonic/activeadmin/blob/main/CONTRIBUTING.md)!
 
 When using [devise](https://github.com/plataformatec/devise) for authentication,
 you can use the [devise-i18n](https://github.com/tigrish/devise-i18n)
@@ -79,7 +82,7 @@ The default namespace is "admin".
 
 ```ruby
 # app/admin/posts.rb
-ActiveAdmin.register Post do
+ActiveAdmin.configure_resource Post do |config|
   # ...
 end
 ```
@@ -139,7 +142,7 @@ ActiveAdmin.setup do |config|
 end
 
 # For a given resource:
-ActiveAdmin.register Post do
+ActiveAdmin.configure_resource Post do |config|
   config.comments = false
 end
 ```
@@ -172,7 +175,7 @@ config.comments_menu = { parent: 'Admin', priority: 1 }
 Remember to indicate where to place the comments and form with:
 
 ```ruby
-active_admin_comments
+active_admin_comments_for(resource)
 ```
 
 ## Utility Navigation

docs/10-custom-pages.md

@@ -1,4 +1,7 @@
 ---
+layout: default
+nav_order: 10
+title: Custom Pages
 redirect_from: /docs/10-custom-pages.html
 ---
 
@@ -19,23 +22,12 @@ Creating a page is as simple as calling `register_page`:
 ```ruby
 # app/admin/calendar.rb
 ActiveAdmin.register_page "Calendar" do
-  content do
-    para "Hello World"
-  end
 end
 ```
 
-Anything rendered within `content` will be the main content on the page.
-Partials behave exactly the same way as they do for resources:
+and defining a partial:
 
 ```ruby
-# app/admin/calendar.rb
-ActiveAdmin.register_page "Calendar" do
-  content do
-    render partial: 'calendar'
-  end
-end
-
 # app/views/admin/calendar/_calendar.html.arb
 table do
   thead do
@@ -80,9 +72,9 @@ ActiveAdmin.register_page "Calendar", namespace: false
 To nest the page within another resource, you can use the `belongs_to` method:
 
 ```ruby
-ActiveAdmin.register Project
+ActiveAdmin.configure_resource Project
 ActiveAdmin.register_page "Status" do
-  belongs_to :project
+  config.belongs_to :project
 end
 ```
 
@@ -93,14 +85,15 @@ and examples.
 
 See the [Sidebars](7-sidebars.md) documentation.
 
-## Add an Action Item
+## Add an Action Link
 
-Just like other resources, you can add action items. The difference here being that
-`:only` and `:except` don't apply because there's only one page it could apply to.
+Just like other resources, you can add action links.
 
 ```ruby
-action_item :view_site do
-  link_to "View Site", "/"
+# app/views/admin/calendar/action_item.html.arb
+div(class: :action_items) do
+  ...
+  action_link "View Site", "/"
 end
 ```
 
@@ -110,25 +103,32 @@ Page actions are custom controller actions (which mirror the resource DSL for
 the same feature).
 
 ```ruby
-page_action :add_event, method: :post do
-  # ...
-  redirect_to admin_calendar_path, notice: "Your event was added"
+# admin/calendar.rb
+# Defines the route `/admin/calendar/add_event` which can handle HTTP POST requests.
+config.add_page_route :add_event, method: :post
+
+# app/controllers/admin/calendar_controller
+class Admin::CalendarController < ActiveAdmin::PageController
+  def add_event
+    # ...
+    redirect_to admin_calendar_path, notice: "Your event was added"
+  end
 end
 
-action_item :add do
-  link_to "Add Event", admin_calendar_add_event_path, method: :post
+# app/views/admin/calendar/action_item.html.arb
+div(class: :action_items) do
+  ...
+  action_link "Add Event", admin_calendar_add_event_path, method: :post
 end
 ```
 
-This defines the route `/admin/calendar/add_event` which can handle HTTP POST requests.
-
 Clicking on the action item will reload page and display the message "Your event
 was added"
 
 Page actions can handle multiple HTTP verbs.
 
 ```ruby
-page_action :add_event, method: [:get, :post] do
+config.add_page_route :add_event, method: [:get, :post] do
   # ...
 end
 ```
@@ -140,10 +140,8 @@ See also the [Custom Actions](8-custom-actions.md#http-verbs) example.
 You can use custom parameter instead of id
 
 ```ruby
-ActiveAdmin.register User do
-  controller do
-    defaults :finder => :find_by_name
-  end
+class Admin::User < ActiveAdmin::ResourceController
+  defaults finder: :find_by_name
 end
 ```