praxis 2.0.pre.9 → 2.0.pre.10

data/lib/api_browser/package.json

@@ -1,43 +0,0 @@
-{
-  "name": "api_doc_browser",
-  "version": "0.13.0",
-  "description": "Praxis API Browser app",
-  "repository": "https://github.com/praxis/praxis",
-  "private": true,
-  "scripts": {
-    "test": "node_modules/.bin/grunt ci"
-  },
-  "author": "",
-  "license": "BSD",
-  "dependencies": {
-    "grunt": "~0.4.2",
-    "grunt-angular-templates": "^0.5.5",
-    "grunt-cli": "^0.1.13",
-    "grunt-contrib-clean": "^0.5.0",
-    "grunt-contrib-concat": "^0.4.0",
-    "grunt-contrib-connect": "^0.7.1",
-    "grunt-contrib-copy": "^0.5.0",
-    "grunt-contrib-cssmin": "^0.9.0",
-    "grunt-contrib-uglify": "^0.4.0",
-    "grunt-contrib-watch": "~0.5.3",
-    "grunt-file-blocks": "^0.3.0",
-    "grunt-filerev": "^0.2.1",
-    "grunt-ng-annotate": "^0.10.0",
-    "grunt-sass": "^1.0.0",
-    "grunt-usemin": "^2.1.1",
-    "grunt-wiredep": "^1.7.0",
-    "load-grunt-tasks": "^0.4.0",
-    "package-merge": "gampleman/package-merge",
-    "bower": "^1.7.0"
-  },
-  "devDependencies": {
-    "grunt-contrib-jshint": "^0.11.0",
-    "grunt-karma": "^0.10.1",
-    "jasmine-core": "^2.2.0",
-    "karma": "^0.12.31",
-    "karma-jasmine": "^0.3.5",
-    "karma-phantomjs-launcher": "^0.1.4",
-    "quick_check": "^0.4.2",
-    "time-grunt": "^0.3.1"
-  }
-}

data/lib/praxis/docs/generator.rb

@@ -1,243 +0,0 @@
-module Praxis
-  module Docs
-
-    class Generator
-      require 'active_support/core_ext/enumerable' # For index_by
-
-      API_DOCS_DIRNAME = 'docs/api'
-
-      attr_reader :resources_by_version, :types_by_id, :infos_by_version
-      attr_reader :doc_root_dir
-
-      EXCLUDED_TYPES_FROM_OUTPUT = Set.new([
-        Attributor::Boolean,
-        Attributor::CSV,
-        Attributor::DateTime,
-        Attributor::Date,
-        Attributor::Float,
-        Attributor::Hash,
-        Attributor::Ids,
-        Attributor::Integer,
-        Attributor::Object,
-        Attributor::String,
-        Attributor::Symbol,
-        Attributor::URI,
-      ]).freeze
-
-
-      def initialize(root)
-        require 'yaml'
-        @resources_by_version =  Hash.new do |h,k|
-          h[k] = Set.new
-        end
-        initialize_directories(root)
-
-        Attributor::AttributeResolver.current = Attributor::AttributeResolver.new
-        collect_infos
-        collect_resources
-        collect_types
-      end
-
-      def save!
-        # Restrict the versions listed in the index file to the ones for which we have at least 1 resource
-        write_index_file( for_versions: resources_by_version.keys )
-        resources_by_version.keys.each do |version|
-          write_version_file(version)
-        end
-      end
-
-      private
-
-      def initialize_directories(root)
-        @doc_root_dir = File.join(root, API_DOCS_DIRNAME)
-
-        # remove previous data (and reset the directory)
-        FileUtils.rm_rf @doc_root_dir if File.exists?(@doc_root_dir)
-        FileUtils.mkdir_p @doc_root_dir unless File.exists? @doc_root_dir
-      end
-
-      def collect_resources
-        # load all resource definitions registered with Praxis
-        Praxis::Application.instance.resource_definitions.map do |resource|
-          # skip resources with doc_visibility of :none
-          next if resource.metadata[:doc_visibility] == :none
-          version = resource.version
-          # TODO: it seems that we shouldn't hardcode n/a in Praxis
-          #  version = "unversioned" if version == "n/a"
-          @resources_by_version[version] << resource
-        end
-      end
-
-      def collect_types
-        @types_by_id = ObjectSpace.each_object( Class ).select do |obj|
-          obj < Attributor::Type
-        end.index_by(&:id)
-      end
-
-      def collect_infos
-        # All infos. Including keys for `:global`, "n/a", and any string version
-        @infos_by_version = ApiDefinition.instance.describe
-      end
-
-
-      # Data: hash/array structure of dumped resources and/or types
-      # processed_types: list of type classes that have already gone through a describe+collect (this or previous rounds)
-      # ... any processed type won't need to be described+reached any longer
-      # newly_found: list of type classes that have been seen in the search (and that weren't already in the processed type)
-      def scan_dump_for_types( data, processed_types )
-        newfound_types = Set.new
-        case data
-        when Array
-          data.collect{|item| newfound_types += scan_dump_for_types( item , processed_types ) }
-        when Hash
-          if data.key?(:type) && data[:type].kind_of?(Hash) && ( [:id,:name,:family] - data[:type].keys ).empty?
-            type_id = data[:type][:id]
-            unless type_id.nil? || type_id == Praxis::SimpleMediaType.id #SimpleTypes shouldn't be collected
-              unless types_by_id[type_id]
-                raise "Error! We have detected a reference to a 'Type' with id='#{type_id}' which is not derived from Attributor::Type" +
-                      " Document generation cannot proceed."
-              end
-              newfound_types << types_by_id[type_id] unless processed_types.include? types_by_id[type_id]
-            end
-          end
-          data.values.map{|item| newfound_types += scan_dump_for_types( item , processed_types)}
-        end
-        newfound_types
-      end
-
-      def write_index_file( for_versions:  )
-        # Gather the versions
-        versions = infos_by_version.keys.reject{|v| v == :global || v == :traits || !for_versions.include?(v) }.map do |version|
-          version == "n/a" ? "unversioned" : version
-        end
-        data = {
-          info: infos_by_version[:global][:info],
-          versions: versions
-          # Note, I don't think we need to report the global traits (but rather the ones in the version)
-        }
-        filename = File.join(doc_root_dir, "index-new.json")
-        puts "Generating Index file: #{filename}"
-        File.open(filename, 'w') {|f| f.write(JSON.pretty_generate(data))}
-      end
-
-      def scan_types_for_version(version, dumped_resources)
-        found_media_types =  resources_by_version[version].select{|r| r.media_type}.collect {|r| r.media_type.describe }
-
-        # We'll start by processing the rendered mediatypes
-        processed_types = Set.new(resources_by_version[version].select do|r|
-          r.media_type && !r.media_type.is_a?(Praxis::SimpleMediaType)
-        end.collect(&:media_type))
-
-        newfound = Set.new
-        found_media_types.each do |mt|
-          newfound += scan_dump_for_types( { type: mt} , processed_types )
-        end
-        # Then will process the rendered resources (noting)
-        newfound += scan_dump_for_types( dumped_resources, Set.new )
-
-        # At this point we've done a scan of the dumped resources and mediatypes.
-        # In that scan we've discovered a bunch of types, however, many of those might have appeared in the JSON
-        # rendered in just shallow mode, so it is not guaranteed that we've seen all the available types.
-        # For that we'll do a (non-shallow) dump of all the types we found, and scan them until the scans do not
-        # yield types we haven't seen before
-        while !newfound.empty? do
-          dumped = newfound.collect(&:describe)
-          processed_types += newfound
-          newfound = scan_dump_for_types( dumped, processed_types )
-        end
-        processed_types
-      end
-
-      def write_version_file( version )
-        version_info = infos_by_version[version]
-        # Hack, let's "inherit/copy" all traits of a version from the global definition
-        # Eventually traits should be defined for a version (and inheritable from global) so we'll emulate that here
-        version_info[:traits] = infos_by_version[:traits]
-
-        dumped_resources = dump_resources( resources_by_version[version] )
-        processed_types = scan_types_for_version(version, dumped_resources)
-        dumped_schemas = dump_schemas( processed_types )
-        full_data = {
-          info: version_info[:info],
-          resources: dumped_resources,
-          schemas: dumped_schemas,
-          traits: version_info[:traits] || []
-        }
-        # Write the file
-        version_file = ( version == "n/a" ? "unversioned" : version )
-        filename = File.join(doc_root_dir, version_file)
-
-        puts "Generating API file: #{filename} (in json and yaml)"
-        File.open(filename+".json", 'w') {|f| f.write(JSON.pretty_generate(full_data))}
-        File.open(filename+".yml", 'w') {|f| f.write(YAML.dump(full_data))}
-      end
-
-
-      def dump_resources( resources )
-        resources.each_with_object({}) do |r, hash|
-          # Do not report undocumentable resources
-          next if r.metadata[:doc_visibility] == :none
-          context = [r.id]
-          resource_description = r.describe(context: context)
-
-          # strip actions with doc_visibility of :none
-          resource_description[:actions].reject! { |a| a[:metadata][:doc_visibility] == :none }
-
-          # Go through the params/payload of each action and augment them by
-          # adding a generated example (then stick it into the description hash)
-          r.actions.each do |action_name, action|
-            # skip actions with doc_visibility of :none
-            next if action.metadata[:doc_visibility] == :none
-
-            action_description = resource_description[:actions].find {|a| a[:name] == action_name }
-          end
-
-          hash[r.id] = resource_description
-        end
-      end
-
-
-      def dump_schemas(types)
-        reportable_types = types - EXCLUDED_TYPES_FROM_OUTPUT
-        reportable_types.each_with_object({}) do |type, array|
-          next if ( type.respond_to?(:anonymous?) && type.anonymous? )
-
-          context = [type.id]
-          example_data = type.example(context)
-          type_output = type.describe(false, example: example_data)
-
-          type_output[:display_name] = type.display_name if type.respond_to?(:display_name)
-          unless type_output[:display_name]
-            # For non MediaTypes or pure types or anonymous types fallback to their name, and worst case to their id
-            type_output[:display_name] = type_output[:name] || type_output[:id]
-          end
-          if type_output[:views]
-            type_output[:views].delete(:master)
-            type_output[:views].each do |view_name, view_info|
-              view_info[:example] = example_data.render(view: view_name)
-            end
-          end
-          type_output[:example] = if example_data.respond_to? :render
-            example_data.render(view: :master)
-          else
-            type.dump(example_data)
-          end
-          array[type.id] = type_output
-        end
-      end
-
-
-      def dump_example_for(context_name, object)
-        example = object.example(Array(context_name))
-        if object.is_a? Praxis::Blueprint
-          example.render(view: :master)
-        elsif object.is_a? Attributor::Attribute
-          object.dump(example)
-        else
-          raise "Do not know how to dump this object (it is not a Blueprint or an Attribute): #{object}"
-        end
-      end
-
-    end
-  end
-end

data/lib/praxis/docs/link_builder.rb

@@ -1,30 +0,0 @@
-module Praxis
-  module Docs
-    # Generates links into the generated doc browser.
-    class LinkBuilder
-      include Singleton
-
-      # Generates a link based on a request gone wrong.
-      # @return [String, nil] The doc browser link.
-      def for_request(req)
-        build_link req.version, 'controller', req.action.resource_definition.id, req.action.name
-      end
-
-      private
-
-      def build_link(*segments)
-        if endpoint
-          endpoint + '#' + segments.join('/')
-        end
-      end
-
-      def endpoint
-        @endpoint ||= begin
-          endpoint = ApiDefinition.instance.global_info.documentation_url
-          endpoint.gsub(/\/index\.html$/i, '/') if endpoint
-        end
-      end
-    end
-
-  end
-end

data/lib/praxis/links.rb

@@ -1,135 +0,0 @@
-module Praxis
-
-  # Container for links for a given type
-  class Links < Praxis::Blueprint
-
-    class DSLCompiler < Attributor::DSLCompiler
-      attr_reader :links
-      def initialize(target, dsl_compiler_options:{}, **options)
-        @links = dsl_compiler_options[:links]
-
-        super
-      end
-
-      def link(name, type=nil, using: name, **opts, &block)
-        links[name] = using
-        if type.nil? && (name != using)
-          type = options[:reference].attributes[using].type
-        end
-        attribute(name, type, **opts, &block)
-      end
-    end
-
-    class << self
-      attr_reader :links
-    end
-
-    def self.for(reference)
-      if defined?(reference::Links)
-        return reference::Links
-      end
-
-      klass = Class.new(self) do
-        @reference = reference
-        @links = Hash.new
-        anonymous_type
-      end
-
-      reference.const_set :Links, klass
-    end
-
-    def self.constructable?
-      true
-    end
-
-    def self.construct(constructor_block, options)
-      options[:reference] = @reference
-      options[:dsl_compiler_options] = {links: self.links}
-
-      self.attributes(options, &constructor_block)
-      self
-    end
-
-    def self.describe(shallow=false,**opts)
-      super(false,**opts) # Links must always describe attributes
-    end
-
-    def self.json_schema_type
-      @attribute.type.json_schema_type
-    end
-
-    def self._finalize!
-      super
-      if @attribute
-        # Master and default views must be set for all attributes, always using their :link view
-        self.define_default_view
-        self.define_master_view
-        self.fixup_reference_struct_methods
-      end
-    end
-
-    def self.define_reader!(name)
-      # it's faster to use define_method in this case than module_eval
-      # because we save the attribute lookup on every access.
-      attribute = self.attributes[name]
-      using = self.links.fetch(name) do
-        raise Exceptions::InvalidConfiguration.new("Cannot define attribute for #{name.inspect}")
-      end
-
-      define_method(name) do
-        value = @object.__send__(using)
-        return value if value.nil? || value.kind_of?(attribute.type)
-        attribute.load(value)
-      end
-
-      # do whatever crazy aliasing we need to here....
-      unless name == using
-        @attribute.type.instance_eval do
-          define_method(using) do
-            self.__send__(name)
-          end
-        end
-      end
-
-    end
-
-    def self.define_default_view
-      return unless view(:default).nil?
-
-      view(:default) {}
-      self.attributes.each do |name, attribute|
-        view(:default).attribute(name, view: :link)
-      end
-    end
-
-    def self.define_master_view
-
-      view(:master) {}
-      self.attributes.each do |name, attribute|
-        view(:master).attribute(name, view: :link)
-      end
-    end
-
-    # Define methods on the inner Struct class for
-    # links that do not have corresponding top-level attributes.
-    # This is primarily necessary only for example generation.
-    def self.fixup_reference_struct_methods
-      self.links.each do |name, using|
-        next if @reference.attribute.attributes.has_key?(using)
-        @reference.attribute.type.instance_eval do
-          define_method(using) do
-            return nil unless attributes[:links]
-            attributes[:links].__send__(name)
-          end
-        end
-      end
-    end
-
-    def self.validate(*args)
-      # FIXME: what to validate for links?
-      []
-    end
-
-  end
-
-end