From 83c099505fb91988edd5c1d09bcd6198abd4335f Mon Sep 17 00:00:00 2001 From: Zachary Scott Date: Mon, 15 May 2017 17:20:50 -0700 Subject: [PATCH] Generate and linkify docs for contrib --- sinatra-contrib/README.md | 50 +++++++---- sinatra-contrib/Rakefile | 3 +- .../lib/sinatra/engine_tracking.rb | 2 + sinatra-contrib/lib/sinatra/runner.rb | 88 +++++++++---------- sinatra-contrib/lib/sinatra/test_helpers.rb | 2 + 5 files changed, 85 insertions(+), 60 deletions(-) diff --git a/sinatra-contrib/README.md b/sinatra-contrib/README.md index 95733d77..0ea097b1 100644 --- a/sinatra-contrib/README.md +++ b/sinatra-contrib/README.md @@ -18,38 +18,38 @@ installed with this gem. Currently included: -* `sinatra/capture`: Let's you capture the content of blocks in templates. +* [`sinatra/capture`][sinatra-capture]: Let's you capture the content of blocks in templates. -* `sinatra/config_file`: Allows loading configuration from yaml files. +* [`sinatra/config_file`][sinatra-config-file]: Allows loading configuration from yaml files. -* `sinatra/content_for`: Adds Rails-style `content_for` helpers to Haml, Erb, +* [`sinatra/content_for`][sinatra-content-for]: Adds Rails-style `content_for` helpers to Haml, Erb, Erubis and Slim. -* `sinatra/cookies`: A `cookies` helper for reading and writing cookies. +* [`sinatra/cookies`][sinatra-cookies]: A `cookies` helper for reading and writing cookies. -* `sinatra/engine_tracking`: Adds methods like `haml?` that allow helper +* [`sinatra/engine_tracking`][sinatra-engine-tracking]: Adds methods like `haml?` that allow helper methods to check whether they are called from within a template. -* `sinatra/json`: Adds a `#json` helper method to return JSON documents. +* [`sinatra/json`][sinatra-json]: Adds a `#json` helper method to return JSON documents. -* `sinatra/link_header`: Helpers for generating `link` HTML tags and +* [`sinatra/link_header`][sinatra-link-header]: Helpers for generating `link` HTML tags and corresponding `Link` HTTP headers. Adds `link`, `stylesheet` and `prefetch` helper methods. -* `sinatra/multi_route`: Adds ability to define one route block for multiple +* [`sinatra/multi_route`][sinatra-multi-route]: Adds ability to define one route block for multiple routes and multiple or custom HTTP verbs. -* `sinatra/namespace`: Adds namespace support to Sinatra. +* [`sinatra/namespace`][sinatra-namespace]: Adds namespace support to Sinatra. -* `sinatra/respond_with`: Choose action and/or template automatically +* [`sinatra/respond_with`][sinatra-respond-with]: Choose action and/or template automatically depending on the incoming request. Adds helpers `respond_to` and `respond_with`. -* `sinatra/custom_logger`: This extension allows you to define your own +* [`sinatra/custom_logger`][sinatra-custom-logger]: This extension allows you to define your own logger instance using +logger+ setting. That logger then will be available as #logger helper method in your routes and views. -* `sinatra/required_params`: Ensure if required query parameters exist +* [`sinatra/required_params`][sinatra-required-params]: Ensure if required query parameters exist ### Custom Extensions @@ -58,13 +58,13 @@ existing APIs. Currently included: -* `sinatra/reloader`: Automatically reloads Ruby files on code changes. +* [`sinatra/reloader`][sinatra-reloader]: Automatically reloads Ruby files on code changes. ### Other Tools -* `sinatra/extension`: Mixin for writing your own Sinatra extensions. +* [`sinatra/extension`][sinatra-extension]: Mixin for writing your own Sinatra extensions. -* `sinatra/test_helpers`: Helper methods to ease testing your Sinatra +* [`sinatra/test_helpers`][sinatra-test-helpers]: Helper methods to ease testing your Sinatra application. Partly extracted from Sinatra. Testing framework agnostic ## Installation @@ -153,3 +153,23 @@ end For more info check the [official docs](http://www.sinatrarb.com/contrib/) and [api docs](http://www.rubydoc.info/gems/sinatra-contrib). + +[sinatra-reloader]: /contrib/reloader +[sinatra-namespace]: /contrib/namespace +[sinatra-content-for]: /contrib/content_for +[sinatra-cookies]: /contrib/cookies +[sinatra-streaming]: /contrib/streaming +[sinatra-webdav]: /contrib/webdav +[sinatra-runner]: /contrib/runner +[sinatra-extension]: /contrib/extension +[sinatra-test-helpers]: /contrib/test_helpers +[sinatra-required-params]: /contrib/required_params +[sinatra-custom-logger]: /contrib/custom_logger +[sinatra-multi-route]: /contrib/multi_route +[sinatra-json]: /contrib/json +[sinatra-respond-with]: /contrib/respond_with +[sinatra-config-file]: /contrib/config_file +[sinatra-link-header]: /contrib/link_header +[sinatra-capture]: /contrib/capture +[sinatra-engine-tracking]: /contrib/engine_tracking + diff --git a/sinatra-contrib/Rakefile b/sinatra-contrib/Rakefile index dfe92354..1ec39dd9 100644 --- a/sinatra-contrib/Rakefile +++ b/sinatra-contrib/Rakefile @@ -11,7 +11,8 @@ task(:default => :spec) namespace :doc do task :readmes do Dir.glob 'lib/sinatra/*.rb' do |file| - excluded_files = %w[lib/sinatra/contrib.rb lib/sinatra/capture.rb lib/sinatra/decompile.rb lib/sinatra/engine_tracking.rb] + puts "Trying file... #{file}" + excluded_files = %w[lib/sinatra/contrib.rb lib/sinatra/decompile.rb] next if excluded_files.include?(file) doc = File.read(file)[/^module Sinatra(\n)+( #[^\n]*\n)*/m].scan(/^ *#(?!#) ?(.*)\n/).join("\n") file = "doc/#{file[4..-4].tr("/_", "-")}.rdoc" diff --git a/sinatra-contrib/lib/sinatra/engine_tracking.rb b/sinatra-contrib/lib/sinatra/engine_tracking.rb index 07db6003..c1e769eb 100644 --- a/sinatra-contrib/lib/sinatra/engine_tracking.rb +++ b/sinatra-contrib/lib/sinatra/engine_tracking.rb @@ -1,6 +1,8 @@ require 'sinatra/base' module Sinatra + # Adds methods like `haml?` that allow helper methods to check whether they + # are called from within a template. module EngineTracking attr_reader :current_engine diff --git a/sinatra-contrib/lib/sinatra/runner.rb b/sinatra-contrib/lib/sinatra/runner.rb index eb00ab91..ae1d0d80 100644 --- a/sinatra-contrib/lib/sinatra/runner.rb +++ b/sinatra-contrib/lib/sinatra/runner.rb @@ -2,51 +2,51 @@ require 'open-uri' require 'net/http' require 'timeout' -# NOTE: This feature is experimental, and missing tests! -# -# Helps you spinning up and shutting down your own sinatra app. This is especially helpful for running -# real network tests against a sinatra backend. -# -# The backend server could look like the following (in test/server.rb). -# -# require "sinatra" -# -# get "/" do -# "Cheers from test server" -# end -# -# get "/ping" do -# "1" -# end -# -# Note that you need to implement a ping action for internal use. -# -# Next, you need to write your runner. -# -# require 'sinatra/runner' -# -# class Runner < Sinatra::Runner -# def app_file -# File.expand_path("../server.rb", __FILE__) -# end -# end -# -# Override Runner#app_file, #command, #port, #protocol and #ping_path for customization. -# -# **Don't forget to override #app_file specific to your application!** -# -# Whereever you need this test backend, here's how you manage it. The following example assumes you -# have a test in your app that needs to be run against your test backend. -# -# runner = ServerRunner.new -# runner.run -# -# # ..tests against localhost:4567 here.. -# -# runner.kill -# -# For an example, check https://github.com/apotonick/roar/blob/master/test/integration/runner.rb module Sinatra + # NOTE: This feature is experimental, and missing tests! + # + # Helps you spinning up and shutting down your own sinatra app. This is especially helpful for running + # real network tests against a sinatra backend. + # + # The backend server could look like the following (in test/server.rb). + # + # require "sinatra" + # + # get "/" do + # "Cheers from test server" + # end + # + # get "/ping" do + # "1" + # end + # + # Note that you need to implement a ping action for internal use. + # + # Next, you need to write your runner. + # + # require 'sinatra/runner' + # + # class Runner < Sinatra::Runner + # def app_file + # File.expand_path("../server.rb", __FILE__) + # end + # end + # + # Override Runner#app_file, #command, #port, #protocol and #ping_path for customization. + # + # **Don't forget to override #app_file specific to your application!** + # + # Whereever you need this test backend, here's how you manage it. The following example assumes you + # have a test in your app that needs to be run against your test backend. + # + # runner = ServerRunner.new + # runner.run + # + # # ..tests against localhost:4567 here.. + # + # runner.kill + # + # For an example, check https://github.com/apotonick/roar/blob/master/test/integration/runner.rb class Runner def app_file File.expand_path("../server.rb", __FILE__) diff --git a/sinatra-contrib/lib/sinatra/test_helpers.rb b/sinatra-contrib/lib/sinatra/test_helpers.rb index 46f1d3af..fd33b0a9 100644 --- a/sinatra-contrib/lib/sinatra/test_helpers.rb +++ b/sinatra-contrib/lib/sinatra/test_helpers.rb @@ -10,6 +10,8 @@ require 'forwardable' module Sinatra Base.set :environment, :test + # Helper methods to ease testing your Sinatra application. Partly extracted + # from Sinatra. Testing framework agnostic module TestHelpers class Session < Rack::Test::Session def global_env