Merge pull request #10 from danleyden/locations

Adding support for inherited mappings

README.md

@@ -199,6 +199,31 @@ DocMyRoutes::Documentation.generate
 ...
 ```
 
+Note: there are occasions where an application may be mounted using url map and
+be composed of other apps by making use of the 'use' directive in rack. In this
+case, you need to tell DocMyRoutes to link the two together. By doing this,
+DocMyRoutes will automatically provide documentation for the child apps mounted
+wherever the composed app ends up being mounted.
+
+e.g.
+
+```ruby
+class MyChildApp; end
+class MyOtherChildApp; end
+
+class MyComposedApp
+  DocMyRoutes::Mapping.inherit_mapping(MyChildApp, self)
+  DocMyRoutes::Mapping.inherit_mapping(MyOtherChildApp, self)
+
+  use MyChildApp
+  use MyOtherChildApp
+end
+
+app = Rack::Builder.app do
+  run Rack::URLMap.new('/myapp' => MyComposedApp.new)
+end
+```
+
 ## Customisation
 
 Some aspects of DocMyRoutes can be customised to provide a different user

lib/doc_my_routes/doc/errors.rb

@@ -3,4 +3,5 @@ module DocMyRoutes
   class ExampleMissing < StandardError; end
   class UnsupportedError < StandardError; end
   class MultipleMappingDetected < UnsupportedError; end
+  class NoMappingDetected < UnsupportedError; end
 end

lib/doc_my_routes/doc/mapping.rb

@@ -36,6 +36,10 @@ def mapping_used?
         Object.const_defined?('Rack::URLMap')
       end
 
+      def inherit_mapping(child_class, super_class)
+        (@inherited_mappings ||= {})[child_class.to_s] = super_class.to_s
+      end
+
       # This method associates to each route its namespace, if detected.
       #
       # Note: when application A is inherited by B and only B is mapped, from
@@ -100,15 +104,19 @@ def mount_point_for_resource(resource)
         class_name = remapped_applications[class_name].first if \
           remapped_applications.key?(class_name)
 
-        locations = route_mapping[class_name]
+        validate_locations(class_name, extract_locations(class_name))
+      end
 
-        validate_locations(class_name, locations)
+      def extract_locations(class_name)
+        route_mapping[class_name] || route_mapping[(@inherited_mappings || {})[class_name]]
       end
 
       # Detects if multiple locations are available and for now fail
       def validate_locations(resource, locations)
-        fail "Resource #{resource} has multiple mappings, but that's not " \
-              "supported yet: #{locations}" if locations.size > 1
+        fail NoMappingDetected, "Resource #{resource} has no mapping, so we can't tell where " \
+          'it is mounted!' if locations.nil?
+        fail MultipleMappingDetected, "Resource #{resource} has multiple mappings, but that's " \
+          "not supported yet: #{locations}" if locations.size > 1
 
         return locations.first if locations.size == 1
 

lib/doc_my_routes/version.rb

@@ -1,4 +1,4 @@
 # DocMyRoutes version
 module DocMyRoutes
-  VERSION = '0.10.0'
+  VERSION = '0.11.0'
 end

spec/system/myapp_spec.rb

@@ -10,6 +10,7 @@
     # The tests are only focused on the route created in each context
     # without taking into consideration the real DocMyRoutes routes
     DocMyRoutes::RouteCollection.routes.clear
+    DocMyRoutes::Mapping.instance_variable_set :@remapped_applications, nil
     reload_app
   end
 
@@ -56,5 +57,36 @@
         expect(subject.map(&:namespace)).to eq(['/myapp', '/myapp'])
       end
     end
+
+    context 'where a different app is mapped that uses that app' do
+      let(:other_class) do
+        Object.send(:remove_const, :MyOtherClass) if Object.constants.include?(:MyOtherClass)
+        MyOtherClass = Class.new do
+          def self.class
+            MyOtherClass
+          end
+        end
+      end
+
+      before do
+        Rack::URLMap.new('/other_app' => other_class)
+      end
+
+      subject { DocMyRoutes::RouteCollection.routes[app_name].map(&:path) }
+
+      it 'fails due to no mapping being available' do
+        expect { subject }.to raise_error DocMyRoutes::NoMappingDetected
+      end
+
+      context 'and the app is marked to inherit the mapping from the different app' do
+        before do
+          DocMyRoutes::Mapping.inherit_mapping(Object.const_get(app_name), MyOtherClass)
+        end
+
+        it 'the routes are correctly namespaced' do
+          expect(subject).to eq(['/other_app', '/other_app'])
+        end
+      end
+    end
   end
 end