From 46beb19e9725b34acdf7be157da23fcc21ccd019 Mon Sep 17 00:00:00 2001 From: Pablo Brasero Date: Tue, 18 Feb 2020 12:19:16 +0000 Subject: [PATCH] Provide tags for doc pages (#1537) Introducing YAML front matter allows us to specify manual titles for each page, which makes it easier to understand which page you're actually on. This is slightly more awkward when viewing `CONTRIBUTING.md` on GitHub, but having titles outweighs that problem. --- CONTRIBUTING.md | 6 ++- Gemfile | 1 + Gemfile.lock | 2 + README.md | 5 +- docs/adding_custom_field_types.md | 4 +- docs/authentication.md | 4 +- docs/authorization.md | 8 ++-- 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 | 14 +++--- docs/rails_api.md | 8 ++-- .../app/controllers/docs_controller.rb | 48 +++++++++++++++++-- .../app/views/layouts/docs.html.erb | 1 + 15 files changed, 91 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcaaff685e..da183d4c32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,6 @@ -# Contributing Guide +--- +title: Contributing Guide +--- ## Code of Conduct @@ -24,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/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 360b870ead..bf844de804 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/README.md b/README.md index dc6dde381e..926d296cce 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,7 @@ -# Administrate +--- +title: Administrate +home: true +--- [![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) 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..8e84875f0a 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. @@ -37,7 +39,7 @@ class PostPolicy < ApplicationPolicy def resolve scope.all end - + def resolve_admin scope.where(owner: user) end @@ -62,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/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..72f645f6b1 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. @@ -84,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: @@ -98,7 +100,7 @@ Example: the_new_attribute: Field::String, # ... }.freeze - + SHOW_PAGE_ATTRIBUTES = [ # ... :the_new_attribute, @@ -110,7 +112,7 @@ Example: :the_new_attribute, # ... ].freeze - + COLLECTION_ATTRIBUTES = [ # ... :the_new_attribute, # if you want it on the index, also. @@ -118,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 e00d61670c..39f8676426 100644 --- a/docs/rails_api.md +++ b/docs/rails_api.md @@ -1,7 +1,9 @@ -## 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. +we still want to have an admin. To get this working, we recommend updating this config: @@ -29,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 diff --git a/spec/example_app/app/controllers/docs_controller.rb b/spec/example_app/app/controllers/docs_controller.rb index dece8410b7..f551a24fab 100644 --- a/spec/example_app/app/controllers/docs_controller.rb +++ b/spec/example_app/app/controllers/docs_controller.rb @@ -18,7 +18,12 @@ def render_page(name) path = full_page_path(name) if File.exist?(path) - render layout: "docs", html: render_markdown(path).html_safe + 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 else render file: "#{Rails.root}/public/404.html", layout: false, @@ -30,11 +35,44 @@ def full_page_path(page) Rails.root + "../../#{page}.md" end - def render_markdown(path) + def parse_document(path) text = File.read(path) - renderer = Redcarpet::Render::HTML - markdown = Redcarpet::Markdown.new(renderer, REDCARPET_CONFIG) + DocumentParser.new(text) + end + + class DocumentParser + def initialize(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 + @body ||= + begin + renderer = Redcarpet::Render::HTML + markdown = Redcarpet::Markdown.new(renderer, REDCARPET_CONFIG) + + source_text_with_heading = <<~MARKDOWN + # #{title} + + #{source_text} + MARKDOWN + + markdown.render(source_text_with_heading) + end + end + + def title + metadata["title"] + end + + def title_suffix + metadata["home"] ? "" : " - Administrate" + end + + private - markdown.render(text) + attr_reader :source_text, :metadata 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..484f90ed1f 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 %><%= @page_title_suffix %> <%= stylesheet_link_tag "docs", media: "all" %>