betterdocs 0.2.0

data/lib/betterdocs/result_representer_collector.rb

@@ -0,0 +1,82 @@
+module Betterdocs
+  class ResultRepresenterCollector
+    def initialize
+      @properties = {}
+      @links      = {}
+    end
+
+    attr_reader :properties
+
+    attr_reader :links
+
+    def property(property_name)
+      property_name = property_name.to_sym
+      @properties[property_name]
+    end
+
+    def link(link_name)
+      link_name = link_name.to_sym
+      @links[link_name]
+    end
+
+    def add_element(representer, type, name, **options, &block)
+      element = build_element(representer, type, name, options, &block)
+      element.add_to_collector(self)
+    end
+
+    def representer
+      (@properties.values + @links.values).find { |v|
+        v.representer and break v.representer
+      }
+    end
+
+    def nested_properties(path = [])
+      properties.values.each_with_object([]) do |property, result|
+        result << property.below_path(path)
+        if sr = property.sub_representer?
+          result.concat sr.docs.nested_properties(path + property.path)
+        end
+      end
+    end
+
+    def nested_links(path = [])
+      result = links.values.map { |l| l.below_path(path) }
+      properties.values.each_with_object(result) do |property, result|
+        if sr = property.sub_representer?
+          nested_property = property.below_path(path)
+          links = sr.docs.nested_links(nested_property.path)
+          result.concat links
+        end
+      end
+      result
+    end
+
+    def to_s
+      result = "*** #{representer} ***\n"
+      if properties = @properties.values.full?
+        result << "\nProperties:"
+        nested_properties.each_with_object(result) do |property, r|
+          r << "\n#{property.full_name}: (#{property.types * '|'}): #{property.description}\n"
+        end
+      end
+      if links = @links.values.full?
+        result << "\nLinks:"
+        links.each_with_object(result) do |link, r|
+          r << "\n#{link.full_name}: #{link.description}\n" # TODO resolve link.url in some useful way
+        end
+      end
+      result
+    end
+
+    private
+
+    def build_element(representer, type, *args, &block)
+      begin
+        element = Dsl::Result.const_get(type.to_s.camelcase)
+      rescue NameError => e
+        raise ArgumentError, "unknown documentation element type #{type.inspect}"
+      end
+      element.new(representer, *args, &block)
+    end
+  end
+end

data/lib/betterdocs/section.rb

@@ -0,0 +1,6 @@
+require 'tins/named_set'
+
+module Betterdocs
+  class Section < Tins::NamedSet
+  end
+end

data/lib/betterdocs/tasks/doc.rake

@@ -0,0 +1,55 @@
+namespace :doc do
+  desc "Create the API documentation"
+  task :api => :'doc:api:sandbox' do
+    Betterdocs::Global.config do |config|
+      Betterdocs::Generator::Markdown.new(only: ENV['ONLY']).generate
+      cd config.output_directory do
+        File.open('.gitignore', 'w') { |ignore| ignore.puts config.ignore }
+      end
+    end
+  end
+
+  task :set_betterdocs_env do
+    ENV['BETTERDOCS'] = '1'
+  end
+
+  namespace :api do
+    desc 'Let database transactions run in a sandboxed environment'
+    task :sandbox => [:'doc:set_betterdocs_env', :environment] do
+
+      ActiveRecord::Base.connection.begin_db_transaction
+      at_exit do
+         ActiveRecord::Base.connection.rollback_db_transaction
+      end
+    end
+
+    desc "Push the newly created API documentation to the remote git repo"
+    task :push => :api do
+      Betterdocs::Global.config do |config|
+        config.publish_git or fail "Configure a git repo as publish_git to publish to"
+        cd config.output_directory do
+          File.directory?('.git') or sh "git init"
+          sh "git remote rm publish_git || true"
+          sh "git remote add publish_git #{config.publish_git}"
+          sh "git add -A"
+          sh 'git commit -m "Add some more changes to API documentation" || true'
+          sh 'git push -f publish_git master'
+        end
+      end
+    end
+
+    desc "Publish the newly created API documentation"
+    task :publish => [ :push ]
+
+    desc "Publish and view the newly created API documentation"
+    task :view => :publish do
+      Betterdocs::Global.config do |config|
+        url = config.publish_git
+        if url !~ /\Ahttps?:/
+          url.sub!(/.*?([^@]*):/, 'http://\1/')
+        end
+        sh "open #{url.inspect}"
+      end
+    end
+  end
+end

data/lib/betterdocs/version.rb

@@ -0,0 +1,8 @@
+module Betterdocs
+  # Betterdocs version
+  VERSION         = '0.2.0'
+  VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
+  VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
+  VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:
+  VERSION_BUILD   = VERSION_ARRAY[2] # :nodoc:
+end

data/spec/controller_dsl_spec.rb

@@ -0,0 +1,143 @@
+require 'spec_helper'
+
+RSpec.describe 'controller dsl' do
+  let :docs do
+    Betterdocs::ControllerCollector.new
+  end
+
+  let :rails do
+    double(application: double(routes: double(url_for: 'http://foo/bar')))
+  end
+
+  let :controller do
+    Module.new do
+      class << self
+        def name
+          'MyTestController'
+        end
+
+        alias to_s name
+      end
+
+
+      def foo
+      end
+    end
+  end
+
+  it "cannot add unknown element types" do
+    expect {
+      docs.add_element controller, :foobar, 'my_foobar' do
+      end
+    }.to raise_error(ArgumentError)
+  end
+
+  context 'controller' do
+    it "can add a new controller" do
+      docs.add_element controller, :controller do
+        description 'my description'
+        section     :test_section
+      end
+      allow(Betterdocs).to receive(:rails).and_return rails
+      my_controller = docs.controller
+      expect(my_controller).to be_present
+      expect(my_controller.name).to eq :my_test
+      expect(my_controller.section).to eq :test_section
+      expect(my_controller.controller).to eq controller
+      expect(my_controller.description).to eq 'my description'
+      expect(my_controller.url).to eq 'http://foo/bar'
+      expect(docs.to_s).to eq(<<EOT)
+MyTestController
+
+url: http://foo/bar
+
+my description
+
+===============================================================================
+
+EOT
+    end
+
+    it 'can be represented as a string if empty' do
+      expect(docs.to_s).to eq(
+        "\n===============================================================================\n\n"
+      )
+    end
+  end
+
+  module MyActionJsonParams
+    include Betterdocs::JsonParamsRepresenter
+
+    param :baz do
+      description 'Some string'
+      types       String
+      value       'baz'
+    end
+  end
+
+  SomeParamsTrait = Betterdocs.trait do
+    param :quux do
+    end
+  end
+
+  context 'action' do
+    it "can add a new action" do
+      docs.add_element controller, :controller do
+        description 'my controller description'
+        section     :test_section
+      end
+      docs.add_element controller, :action do
+        description 'my description'
+        section     :test_section2
+        http_method :GET
+
+        param :bar do
+        end
+
+        param :baz do
+          use_in_url no
+        end
+
+        include_params SomeParamsTrait
+
+        json_params_like MyActionJsonParams
+      end
+      allow(Betterdocs).to receive(:rails).and_return rails
+      expect(docs.actions).to be_empty
+      docs.configure_current_element(:foo)
+      expect(docs.actions.size).to eq 1
+      expect(action = docs.action(:foo)).to be_present
+      expect(action.controller).to eq controller
+      expect(action.name).to eq :foo
+      expect(action.section).to eq :test_section2
+      expect(docs.section).to eq :test_section
+      expect(action.action_method).to eq controller.instance_method(:foo)
+      expect(action.http_method).to eq :GET
+      expect(action.params).to have_key :bar
+      expect(action.params).to have_key :quux
+      expect(action.json_params).to have_key :baz
+      expect(action.url).to eq 'http://foo/bar'
+      expect(docs.to_s.sub(%r(.*(betterdocs/.*)), '\1')).to eq(<<EOT)
+MyTestController
+
+url: http://foo/bar
+
+my controller description
+
+===============================================================================
+GET http://foo/bar
+
+MyTestController#foo(bar, baz, quux)
+
+bar(=1): TODO
+baz(=2): TODO
+quux(=3): TODO
+
+my description
+
+betterdocs/spec/controller_dsl_spec.rb:23
+
+EOT
+    end
+  end
+end

data/spec/generator/markdown_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+RSpec.describe Betterdocs::Generator::Markdown do
+  it "does all kinds of stuff correctly"
+end

data/spec/json_params_representer_spec.rb

@@ -0,0 +1,79 @@
+require 'spec_helper'
+
+RSpec.describe Betterdocs::JsonParamsRepresenter do
+  module MyJsonParams
+    include Betterdocs::JsonParamsRepresenter
+
+    param :string do
+      description 'Some string'
+      types    String
+      value    'peter.paul@betterplace.org'
+    end
+
+    param :number do
+      description 'some integer number'
+      types       Integer
+      value       666
+      required    yes
+    end
+
+    param :flag do
+      description 'some boolean flag'
+      types       [ true, false ]
+      value       true
+      required    no
+    end
+  end
+
+  let :object do
+    OpenStruct.new.tap do |o|
+      o.string = 'some string'
+      o.number = 666
+      o.flag   = true
+      MyJsonParams.apply(o)
+    end
+  end
+
+  let :docs do
+    MyJsonParams.docs
+  end
+
+  it 'can be converted into a ActionController::Parameters instance' do
+    expect(object.as_json).to be_a ActionController::Parameters
+  end
+
+  it 'it can be turned into a hash' do
+    expect(object.as_json).to eq("string" => "some string", "number" => 666, "flag" => true)
+  end
+
+  it 'it can be turned into json' do
+    expect(object.to_json).to eq '{"string":"some string","number":666,"flag":true}'
+  end
+
+  it 'can check a parameter hash' do
+    skip
+  end
+
+  it 'can return all the documented parameters as a hash' do
+    expect(docs.params.keys).to eq %i[ string number flag ]
+  end
+
+  context '#param' do
+    let :param do
+      docs.param(:string)
+    end
+
+    it 'can return a single documented parameter' do
+      expect(param).to be_a Betterdocs::Dsl::JsonParams::Param
+      expect(param.description).to eq 'Some string'
+      expect(param.value).to eq 'peter.paul@betterplace.org'
+      expect(param.types).to eq %w[ string ]
+      expect(param.required).to eq true
+    end
+  end
+
+  it 'foos' do
+    puts docs.to_s
+    skip
+  end
+end

data/spec/json_type_mapper_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+RSpec.describe Betterdocs::Dsl::JsonTypeMapper do
+  let :jtm do Betterdocs::Dsl::JsonTypeMapper end
+
+  it "derives json types" do
+    expect(jtm.derive_json_type_from(true)).to eq 'boolean'
+    expect(jtm.derive_json_type_from(TrueClass)).to eq 'boolean'
+    expect(jtm.derive_json_type_from(false)).to eq 'boolean'
+    expect(jtm.derive_json_type_from(FalseClass)).to eq 'boolean'
+    expect(jtm.derive_json_type_from(nil)).to eq 'null'
+    expect(jtm.derive_json_type_from(NilClass)).to eq 'null'
+    expect(jtm.derive_json_type_from(42)).to eq 'number'
+    expect(jtm.derive_json_type_from(Fixnum)).to eq 'number'
+    expect(jtm.derive_json_type_from(42)).to eq 'number'
+    expect(jtm.derive_json_type_from(Fixnum)).to eq 'number'
+    expect(jtm.derive_json_type_from(Math::PI)).to eq 'number'
+    expect(jtm.derive_json_type_from(Float)).to eq 'number'
+    expect(jtm.derive_json_type_from([])).to eq 'array'
+    expect(jtm.derive_json_type_from(Array)).to eq 'array'
+    expect(jtm.derive_json_type_from({})).to eq 'object'
+    expect(jtm.derive_json_type_from(Hash)).to eq 'object'
+    expect(jtm.derive_json_type_from('foo')).to eq 'string'
+    expect(jtm.derive_json_type_from(String)).to eq 'string'
+  end
+
+  it "maps arrays of ruby types correctly" do
+    expect(jtm.map_types([])).to eq %w[ array ]
+    expect(jtm.map_types([ [] ])).to eq %w[ array ]
+    expect(jtm.map_types([ [], {}, Array, nil, Hash ])).to eq %w[ array null object ]
+    expect(jtm.map_types("foo")).to eq %w[ string ]
+  end
+end

data/spec/result_representer_dsl_spec.rb

@@ -0,0 +1,183 @@
+require 'spec_helper'
+
+RSpec.describe 'representer dsl' do
+  let :docs do
+    Betterdocs::ResultRepresenterCollector.new
+  end
+
+  let :representer do
+    Module.new do
+      def self.property(*)
+        @property_set = true
+      end
+
+      def self.has_property_set?
+        @property_set
+      end
+
+      def self.link(*)
+        @link_set = true
+      end
+
+      def self.has_link_set?
+        @link_set
+      end
+
+      def self.to_s
+        'MyRepresenter'
+      end
+    end
+  end
+
+  it "cannot add unknown element types" do
+    expect {
+      docs.add_element representer, :foobar, 'my_foobar' do
+      end
+    }.to raise_error(ArgumentError)
+  end
+
+  context 'property' do
+    it "can add a new property" do
+      docs.add_element representer, :property, 'my_property' do
+        # XXX as          :foo_bar
+        description 'my description'
+        types       [ String, nil ]
+      end
+      property = docs.property(:my_property)
+      expect(property).to be_present
+      expect(property.name).to eq :my_property
+      expect(property.representer).to eq representer
+      expect(property.description).to eq 'my description'
+      expect(property.types).to eq %w[ null string ]
+      expect(property.example).to eq 'TODO' # TODO
+    end
+
+    it "can define a property on representer" do
+      docs.add_element representer, :property, 'my_property' do
+      end
+      property = docs.property(:my_property)
+      expect(property).to be_present
+    end
+  end
+
+  context 'link' do
+    it "cannot add a new link without url" do
+      docs.add_element representer, :link, 'my_link' do
+      end
+      link = docs.link(:my_link)
+      expect { link.url }.to raise_error(ArgumentError)
+    end
+
+    it "can add a new link" do
+      docs.add_element representer, :link, 'my_link' do
+        description 'my URL description'
+        url         { 'http://foo.bar' }
+      end
+      link = docs.link(:my_link)
+      expect(link).to be_present
+      expect(link.name).to eq :my_link
+      expect(link.representer).to eq representer
+      expect(link.description).to eq 'my URL description'
+    end
+
+    it "can define a templated link" do
+      docs.add_element representer, :link, 'my_link' do
+        description 'my URL description'
+        url         { 'http://foo.bar' }
+        templated yes
+      end
+      link = docs.link(:my_link)
+      expect(link).to be_present
+      expect(link.templated).to eq true
+    end
+  end
+
+  it 'can return a string representation of all its links/properties' do
+    docs.add_element representer, :property, 'my_property' do
+      # XXX as          :foo_bar
+      description 'my description'
+      types       [ String, nil ]
+    end
+    docs.add_element representer, :property, 'my_property2' do
+      description 'my description2'
+      types       [ true, false ]
+    end
+    docs.add_element representer, :link, 'my_link' do
+      description 'my URL description'
+      url         { 'http://foo.bar' }
+    end
+    docs.add_element representer, :link, 'my_link2' do
+      description 'my URL description2'
+      url         { 'http://foo.baz' }
+    end
+    expect(docs.to_s).to eq <<EOT
+*** MyRepresenter ***
+
+Properties:
+my_property: (null|string): my description
+
+my_property2: (boolean): my description2
+
+Links:
+my_link: my URL description
+
+my_link2: my URL description2
+EOT
+  end
+
+  context 'nesting representers' do
+    module Location
+      include Betterdocs::ResultRepresenter
+
+      property :latitude
+
+      property :longitude
+
+      link :dot do
+        url { 'http://foo.bar/dot' }
+      end
+    end
+
+    module Address
+      include Betterdocs::ResultRepresenter
+
+      property :city
+
+      property :location do
+        represent_with Location
+      end
+
+      link :map do
+        url { 'http://foo.bar/map' }
+      end
+    end
+
+
+    module Person
+      include Betterdocs::ResultRepresenter
+
+      property :name
+
+      property :address do
+        represent_with Address
+      end
+
+      link :self do
+        url { 'http://foo.bar' }
+      end
+    end
+
+    it 'can return an array of its nested properties' do
+      expect(Person.docs.nested_properties.size).to eq 6
+      expect(Person.docs.nested_properties.map(&:full_name)).to eq [ "name",
+        "address", "address.city", "address.location",
+        "address.location.latitude", "address.location.longitude" ]
+    end
+
+    it 'can return an array of its nested links' do
+      expect(Person.docs.nested_links.size).to eq 3
+      expect(Person.docs.nested_links.map(&:full_name)).to eq [
+        "self", "address.map", "address.location.dot" ]
+    end
+  end
+end