From 8710d091c0f7c0baeed62b45b128968c83104425 Mon Sep 17 00:00:00 2001 From: Pablo Brasero Date: Thu, 23 Jan 2020 15:44:17 +0000 Subject: [PATCH 1/6] Provide tags for doc pages --- .../app/controllers/docs_controller.rb | 41 ++++++++++++++++--- .../app/views/layouts/docs.html.erb | 1 + 2 files changed, 37 insertions(+), 5 deletions(-) diff --git a/spec/example_app/app/controllers/docs_controller.rb b/spec/example_app/app/controllers/docs_controller.rb index dece8410b7..450efa2103 100644 --- a/spec/example_app/app/controllers/docs_controller.rb +++ b/spec/example_app/app/controllers/docs_controller.rb @@ -18,7 +18,11 @@ def render_page(name) path = full_page_path(name) if File.exist?(path) - render layout: "docs", html: render_markdown(path).html_safe + contents = parse_markdown(path) + @page_title = contents.title + # rubocop:disable Rails/OutputSafety + render layout: "docs", html: contents.body.html_safe + # rubocop:enable Rails/OutputSafety else render file: "#{Rails.root}/public/404.html", layout: false, @@ -30,11 +34,38 @@ def full_page_path(page) Rails.root + "../../#{page}.md" end - def render_markdown(path) + def parse_markdown(path) text = File.read(path) - renderer = Redcarpet::Render::HTML - markdown = Redcarpet::Markdown.new(renderer, REDCARPET_CONFIG) + MarkdownParser.new(text) + end + + class MarkdownParser + def initialize(source_text) + @source_text = source_text + end + + def body + @body ||= + begin + renderer = Redcarpet::Render::HTML + markdown = Redcarpet::Markdown.new(renderer, REDCARPET_CONFIG) + + markdown.render(source_text) + end + end + + def title + @title ||= + begin + h1_match = @source_text.scan(/^# (.*)$/).first + raise "Please provide an H1 heading for the page" if h1_match.empty? + + h1_match.first + end + end + + private - markdown.render(text) + attr_reader :source_text end end diff --git a/spec/example_app/app/views/layouts/docs.html.erb b/spec/example_app/app/views/layouts/docs.html.erb index fe9096581c..b4e7c74c70 100644 --- a/spec/example_app/app/views/layouts/docs.html.erb +++ b/spec/example_app/app/views/layouts/docs.html.erb @@ -2,6 +2,7 @@ <html lang="en"> <head> <meta charset="utf-8" /> + <title><%= @page_title %> <%= stylesheet_link_tag "docs", media: "all" %> From f67559ee33375a9a39f7465f5dc0401d04f15b40 Mon Sep 17 00:00:00 2001 From: Pablo Brasero Date: Thu, 13 Feb 2020 11:02:28 +0000 Subject: [PATCH 2/6] Less hacky, allows for future enhancements --- CONTRIBUTING.md | 4 +++- Gemfile | 1 + Gemfile.lock | 2 ++ docs/adding_custom_field_types.md | 4 +++- docs/authentication.md | 4 +++- docs/authorization.md | 4 +++- docs/customizing_attribute_partials.md | 4 +++- docs/customizing_controller_actions.md | 4 +++- docs/customizing_dashboards.md | 4 +++- docs/customizing_page_views.md | 4 +++- docs/getting_started.md | 4 +++- docs/rails_api.md | 4 +++- .../app/controllers/docs_controller.rb | 22 ++++++++----------- 13 files changed, 42 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcaaff685e..9d8194cbe8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,6 @@ -# Contributing Guide +--- +title: Contributing Guide +--- ## Code of Conduct diff --git a/Gemfile b/Gemfile index f638614366..7ef5899244 100644 --- a/Gemfile +++ b/Gemfile @@ -5,6 +5,7 @@ gemspec gem "administrate-field-image" gem "autoprefixer-rails" gem "faker" +gem "front_matter_parser" gem "globalid" gem "pg" gem "redcarpet" diff --git a/Gemfile.lock b/Gemfile.lock index 3f7b4e9105..36307da199 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -99,6 +99,7 @@ GEM activesupport capybara i18n + front_matter_parser (0.2.1) globalid (0.4.2) activesupport (>= 4.2.0) hashdiff (1.0.0) @@ -265,6 +266,7 @@ DEPENDENCIES factory_bot_rails faker formulaic + front_matter_parser globalid i18n-tasks (= 0.9.30) launchy diff --git a/docs/adding_custom_field_types.md b/docs/adding_custom_field_types.md index bc1191e4b8..a75644d415 100644 --- a/docs/adding_custom_field_types.md +++ b/docs/adding_custom_field_types.md @@ -1,4 +1,6 @@ -# Adding Custom Field Types +--- +title: Adding Custom Field Types +--- If your application deals with a nonstandard data type, you can create an `Administrate::Field` object to help display diff --git a/docs/authentication.md b/docs/authentication.md index 91a4285c03..548a36a279 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,4 +1,6 @@ -# Authenticating admin users +--- +title: Authenticating admin users +--- Authentication is left for you to implement after you install Administrate into your app. It's expected that you can plugin your existing authentication diff --git a/docs/authorization.md b/docs/authorization.md index 2c5548add6..3f94ade1a4 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -1,4 +1,6 @@ -# Authorization +--- +title: Authorization +--- The default configuration of Administrate is "authenticate-only" - once a user is authenticated, that user has access to every action of every object. diff --git a/docs/customizing_attribute_partials.md b/docs/customizing_attribute_partials.md index 1be446e1c2..ceb02ed45b 100644 --- a/docs/customizing_attribute_partials.md +++ b/docs/customizing_attribute_partials.md @@ -1,4 +1,6 @@ -# Customizing attribute partials +--- +title: Customizing attribute partials +--- Occasionally you might want to change how specific types of attributes appear across all dashboards. You can customize the following built in field types: diff --git a/docs/customizing_controller_actions.md b/docs/customizing_controller_actions.md index c0f058c19a..c333050863 100644 --- a/docs/customizing_controller_actions.md +++ b/docs/customizing_controller_actions.md @@ -1,4 +1,6 @@ -# Customizing controller actions +--- +title: Customizing controller actions +--- When you install Administrate into your app, we generate empty controllers for each of your resources. diff --git a/docs/customizing_dashboards.md b/docs/customizing_dashboards.md index 42fcef90ef..ffaaf8d998 100644 --- a/docs/customizing_dashboards.md +++ b/docs/customizing_dashboards.md @@ -1,4 +1,6 @@ -# Customizing Dashboards +--- +title: Customizing Dashboards +--- In order to customize which attributes get displayed for each resource, edit the dashboard file generated by the installation generator. diff --git a/docs/customizing_page_views.md b/docs/customizing_page_views.md index d283ed938a..23ece20c37 100644 --- a/docs/customizing_page_views.md +++ b/docs/customizing_page_views.md @@ -1,4 +1,6 @@ -# Customizing page views +--- +title: Customizing page views +--- In order to change the appearance of any page, you can write custom Rails views. diff --git a/docs/getting_started.md b/docs/getting_started.md index 8d9ba72f6b..07c08ceb9e 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,4 +1,6 @@ -# Getting Started +--- +title: Getting Started +--- Administrate is released as a Ruby gem, and can be installed on Rails applications version 4.2 or greater. diff --git a/docs/rails_api.md b/docs/rails_api.md index e00d61670c..56847e85a9 100644 --- a/docs/rails_api.md +++ b/docs/rails_api.md @@ -1,4 +1,6 @@ -## Rails API +--- +title: Rails API +--- Since Rails 5.0, we've been able to have API only applications. Yet, sometimes we still want to have an admin. diff --git a/spec/example_app/app/controllers/docs_controller.rb b/spec/example_app/app/controllers/docs_controller.rb index 450efa2103..cca10acb84 100644 --- a/spec/example_app/app/controllers/docs_controller.rb +++ b/spec/example_app/app/controllers/docs_controller.rb @@ -18,7 +18,7 @@ def render_page(name) path = full_page_path(name) if File.exist?(path) - contents = parse_markdown(path) + contents = parse_document(path) @page_title = contents.title # rubocop:disable Rails/OutputSafety render layout: "docs", html: contents.body.html_safe @@ -34,14 +34,16 @@ def full_page_path(page) Rails.root + "../../#{page}.md" end - def parse_markdown(path) + def parse_document(path) text = File.read(path) - MarkdownParser.new(text) + DocumentParser.new(text) end - class MarkdownParser + class DocumentParser def initialize(source_text) - @source_text = source_text + front_matter_parsed = FrontMatterParser::Parser.new(:md).call(source_text) + @source_text = front_matter_parsed.content + @metadata = front_matter_parsed.front_matter end def body @@ -55,17 +57,11 @@ def body end def title - @title ||= - begin - h1_match = @source_text.scan(/^# (.*)$/).first - raise "Please provide an H1 heading for the page" if h1_match.empty? - - h1_match.first - end + metadata["title"] end private - attr_reader :source_text + attr_reader :source_text, :metadata end end From 8bac53bb591349dc6e4aeaa431b3e57ad94a9340 Mon Sep 17 00:00:00 2001 From: Pablo Brasero Date: Thu, 13 Feb 2020 11:03:06 +0000 Subject: [PATCH 3/6] Remove trailing spaces --- CONTRIBUTING.md | 2 +- docs/authorization.md | 4 ++-- docs/getting_started.md | 10 +++++----- docs/rails_api.md | 4 ++-- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d8194cbe8..da183d4c32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ To maintain compatibility with multiple dependency versions, we use ### Opening a PR 1. Fork the repo, -2. Run `./bin/setup` to install the base dependencies and setup a local +2. Run `./bin/setup` to install the base dependencies and setup a local database, 3. Run the test suite: `bundle exec rspec && bundle exec appraisal rspec`, 4. Make your changes, diff --git a/docs/authorization.md b/docs/authorization.md index 3f94ade1a4..8e84875f0a 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -39,7 +39,7 @@ class PostPolicy < ApplicationPolicy def resolve scope.all end - + def resolve_admin scope.where(owner: user) end @@ -64,7 +64,7 @@ def authorize_resource(resource) raise "Erg!" unless show_action?(params[:action], resource) end -# Hide links to actions if the user is not allowed to do them +# Hide links to actions if the user is not allowed to do them def show_action?(action, resource) current_user.can? action, resource end diff --git a/docs/getting_started.md b/docs/getting_started.md index 07c08ceb9e..72f645f6b1 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -86,8 +86,8 @@ rails generate administrate:install --namespace=supervisor ## Keep Dashboards Updated as Model Attributes Change -If you've installed Administrate and generated dashboards and _then_ -subsequently added attributes to your models you'll need to manually add +If you've installed Administrate and generated dashboards and _then_ +subsequently added attributes to your models you'll need to manually add these additions (or removals) to your dashboards. Example: @@ -100,7 +100,7 @@ Example: the_new_attribute: Field::String, # ... }.freeze - + SHOW_PAGE_ATTRIBUTES = [ # ... :the_new_attribute, @@ -112,7 +112,7 @@ Example: :the_new_attribute, # ... ].freeze - + COLLECTION_ATTRIBUTES = [ # ... :the_new_attribute, # if you want it on the index, also. @@ -120,7 +120,7 @@ Example: ].freeze ``` -It's recommended that you make this change at the same time as you add the +It's recommended that you make this change at the same time as you add the attribute to the model. The alternative way to handle this is to re-run `rails g administrate:install` diff --git a/docs/rails_api.md b/docs/rails_api.md index 56847e85a9..39f8676426 100644 --- a/docs/rails_api.md +++ b/docs/rails_api.md @@ -3,7 +3,7 @@ title: Rails API --- Since Rails 5.0, we've been able to have API only applications. Yet, sometimes -we still want to have an admin. +we still want to have an admin. To get this working, we recommend updating this config: @@ -31,7 +31,7 @@ config.middleware.use ::Rack::MethodOverride ``` You must also ensure that all the required controller actions are available -and accessible as routes since generators in API-only applications only +and accessible as routes since generators in API-only applications only generate some of the required actions. Here is an example: ```ruby From 6b86e8dda05bd14bc11dbcc650684b667b93d292 Mon Sep 17 00:00:00 2001 From: Pablo Brasero Date: Thu, 13 Feb 2020 18:06:33 +0000 Subject: [PATCH 4/6] For index page of docs. A bit awkward on GitHub? --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dc6dde381e..b6a5691568 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# Administrate +--- +title: Administrate +--- [![CircleCI](https://img.shields.io/circleci/project/github/thoughtbot/administrate.svg)](https://circleci.com/gh/thoughtbot/administrate/tree/master) [![Gem Version](https://badge.fury.io/rb/administrate.svg)](https://badge.fury.io/rb/administrate) From 7cd3cf24565bf703f2de2e33f2c51b3a8eb5067d Mon Sep 17 00:00:00 2001 From: Pablo Brasero Date: Thu, 13 Feb 2020 18:20:02 +0000 Subject: [PATCH 5/6] Provide some context in the page title --- README.md | 1 + spec/example_app/app/controllers/docs_controller.rb | 5 +++++ spec/example_app/app/views/layouts/docs.html.erb | 2 +- 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b6a5691568..926d296cce 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ --- title: Administrate +home: true --- [![CircleCI](https://img.shields.io/circleci/project/github/thoughtbot/administrate.svg)](https://circleci.com/gh/thoughtbot/administrate/tree/master) diff --git a/spec/example_app/app/controllers/docs_controller.rb b/spec/example_app/app/controllers/docs_controller.rb index cca10acb84..2b9865c4ab 100644 --- a/spec/example_app/app/controllers/docs_controller.rb +++ b/spec/example_app/app/controllers/docs_controller.rb @@ -20,6 +20,7 @@ def render_page(name) if File.exist?(path) contents = parse_document(path) @page_title = contents.title + @page_title_suffix = contents.title_suffix # rubocop:disable Rails/OutputSafety render layout: "docs", html: contents.body.html_safe # rubocop:enable Rails/OutputSafety @@ -60,6 +61,10 @@ def title metadata["title"] end + def title_suffix + metadata["home"] ? "" : " - Administrate" + end + private attr_reader :source_text, :metadata diff --git a/spec/example_app/app/views/layouts/docs.html.erb b/spec/example_app/app/views/layouts/docs.html.erb index b4e7c74c70..484f90ed1f 100644 --- a/spec/example_app/app/views/layouts/docs.html.erb +++ b/spec/example_app/app/views/layouts/docs.html.erb @@ -2,7 +2,7 @@ - <%= @page_title %> + <%= @page_title %><%= @page_title_suffix %> <%= stylesheet_link_tag "docs", media: "all" %> From 5086d79d55a4cf721e5e2ae7b3a723a344a4f1d9 Mon Sep 17 00:00:00 2001 From: Pablo Brasero Date: Thu, 13 Feb 2020 18:26:18 +0000 Subject: [PATCH 6/6] Put top headings back in pages --- spec/example_app/app/controllers/docs_controller.rb | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/spec/example_app/app/controllers/docs_controller.rb b/spec/example_app/app/controllers/docs_controller.rb index 2b9865c4ab..f551a24fab 100644 --- a/spec/example_app/app/controllers/docs_controller.rb +++ b/spec/example_app/app/controllers/docs_controller.rb @@ -53,7 +53,13 @@ def body renderer = Redcarpet::Render::HTML markdown = Redcarpet::Markdown.new(renderer, REDCARPET_CONFIG) - markdown.render(source_text) + source_text_with_heading = <<~MARKDOWN + # #{title} + + #{source_text} + MARKDOWN + + markdown.render(source_text_with_heading) end end