MM: Improve breadcrumbs

Make the page breadcrumbs actually reflect the navigation hierarchy.

Include a type's module name when it's from an external module or
not clear from the breadcrumb list.

Affects all specs.

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 ##### Enhancements
 
+* Improve page breadcrumbs to include parent pages and indicate source module
+  of extensions from other modules.  
+  [John Fairhurst](https://github.com/johnfairh)
+
 * Add `--readme-title` and `--docset-title` to set the titles of the readme
   docs page and the Dash docset independently of the module name.  
   [John Fairhurst](https://github.com/johnfairh)

lib/jazzy/config.rb

@@ -690,6 +690,10 @@ def module_name?(name)
       @module_names_set.include?(name)
     end
 
+    def multiple_modules?
+      @module_names.count > 1
+    end
+
     def parse_module_configs
       return [self] unless modules_configured
 

lib/jazzy/doc_builder.rb

@@ -250,7 +250,8 @@ def self.new_document(source_module, doc_model)
         doc[:doc_coverage] = source_module.doc_coverage unless
           Config.instance.hide_documentation_coverage
         doc[:structure] = source_module.doc_structure
-        doc[:module_name] = source_module.readme_title # historical name
+        doc[:readme_title] = source_module.readme_title
+        doc[:module_name] = doc[:readme_title]
         doc[:author_name] = source_module.author_name
         if source_host = source_module.host
           doc[:source_host_name] = source_host.name
@@ -261,6 +262,7 @@ def self.new_document(source_module, doc_model)
           doc[:github_token_url] = doc[:source_host_item_url]
         end
         doc[:dash_url] = source_module.dash_feed_url
+        doc[:breadcrumbs] = make_breadcrumbs(doc_model)
       end
     end
 
@@ -270,7 +272,7 @@ def self.new_document(source_module, doc_model)
     # @param [String] path_to_root
     def self.document_markdown(source_module, doc_model, path_to_root)
       doc = new_document(source_module, doc_model)
-      name = doc_model.name == 'index' ? source_module.readme_title : doc_model.name
+      name = doc_model.readme? ? source_module.readme_title : doc_model.name
       doc[:name] = name
       doc[:overview] = render(doc_model, doc_model.content(source_module))
       doc[:path_to_root] = path_to_root
@@ -448,5 +450,28 @@ def self.document(source_module, doc_model, path_to_root)
       doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
     end
     # rubocop:enable Metrics/MethodLength
+
+    # Breadcrumbs for a page - doesn't include the top 'readme' crumb
+    def self.make_breadcrumbs(doc_model)
+      return [] if doc_model.readme?
+
+      docs_path = doc_model.docs_path
+      breadcrumbs = docs_path.map do |doc|
+        {
+          name: doc.name,
+          url: doc.url,
+          last: doc == doc_model,
+        }
+      end
+
+      return breadcrumbs if breadcrumbs.count == 1
+
+      # Add the module name to the outer type if not clear from context
+      if docs_path[1].ambiguous_module_name?(docs_path[0].name)
+        breadcrumbs[1][:name] = docs_path[1].fully_qualified_module_name
+      end
+
+      breadcrumbs
+    end
   end
 end

lib/jazzy/source_declaration.rb

@@ -62,6 +62,7 @@ def namespace_ancestors
       end
     end
 
+    # 'OuterType.NestedType.method(arg:)'
     def fully_qualified_name
       namespace_path.map(&:name).join('.')
     end
@@ -74,6 +75,17 @@ def fully_qualified_name_regexp
                                .join('(?:<.*?>)?\.'))
     end
 
+    # 'MyModule.OuterType.NestedType.method(arg:)'
+    def fully_qualified_module_name
+      prefix = module_name&.then { _1 + '.' } || ''
+      prefix + fully_qualified_name
+    end
+
+    # List of doc_parent decls, .last is self
+    def docs_path
+      (parent_in_docs&.docs_path || []) + [self]
+    end
+
     # If this declaration is an objc category, returns an array with the name
     # of the extended objc class and the category name itself, i.e.
     # ["NSString", "MyMethods"], nil otherwise.
@@ -199,9 +211,20 @@ def type_from_doc_module?
     # Don't ask the user to write documentation for types being extended
     # from other modules.  Compile errors leave no docs and a `nil` USR.
     def mark_undocumented?
-      !swift? || (usr &&
-        (module_name.nil? ||
-          Config.instance.module_name?(module_name)))
+      !swift? || (usr && !extension_of_external_type?)
+    end
+
+    def extension_of_external_type?
+      !module_name.nil? &&
+        !Config.instance.module_name?(module_name)
+    end
+
+    # Is it unclear from context what module the (top-level) decl is from?
+    def ambiguous_module_name?(group_name)
+      extension_of_external_type? ||
+        (Config.instance.multiple_modules? &&
+          !module_name.nil? &&
+          group_name != module_name)
     end
 
     # Info text for contents page by collapsed item name
@@ -212,6 +235,10 @@ def declaration_note
       notes.join(', ').humanize unless notes.empty?
     end
 
+    def readme?
+      false
+    end
+
     def alternative_abstract
       if file = alternative_abstract_file
         Pathname(file).read

lib/jazzy/source_document.rb

@@ -27,6 +27,10 @@ def self.make_index(readme_path)
       end
     end
 
+    def readme?
+      url == 'index.html'
+    end
+
     def render_as_page?
       true
     end

lib/jazzy/source_module.rb

@@ -25,8 +25,8 @@ def initialize(docs, doc_structure, doc_coverage, docset_builder)
       self.docs = docs
       self.doc_structure = doc_structure
       self.doc_coverage = doc_coverage
-      self.readme_title =
-        config.readme_title || config.module_names.first
+      title = config.readme_title || config.module_names.first
+      self.readme_title = title.empty? ? 'Index' : title
       self.author_name = config.author_name
       self.author_url = config.author_url
       self.host = SourceHost.create(config)

lib/jazzy/sourcekitten.rb

@@ -655,7 +655,8 @@ def self.make_source_declarations(docs, parent = nil, mark = SourceMark.new)
         declaration.type_usr = doc['key.typeusr']
         declaration.module_name =
           if declaration.swift?
-            doc['key.modulename']
+            # Filter out Apple sub-framework implementation names
+            doc['key.modulename']&.sub(/\..*$/, '')
           else
             # ObjC best effort, category original module is unavailable
             @current_module_name

lib/jazzy/themes/apple/assets/css/jazzy.css.scss

@@ -23,7 +23,7 @@ $content_top_offset: 70px;
 $content_body_margin: 16px;
 $content_body_left_offset: $sidebar_width + $content_body_margin;
 $header_height: 32px;
-$breadcrumb_padding_top: 17px;
+$breadcrumb_padding_top: 12px;
 
 $code_font: 0.95em Menlo, monospace;
 
@@ -206,9 +206,11 @@ header {
   height: $content_top_offset - $header_height - $breadcrumb_padding_top;
   padding-top: $breadcrumb_padding_top;
   position: fixed;
-  width: 100%;
+  width: inherit;
   z-index: 2;
   margin-top: $header_height;
+  white-space: nowrap;
+  overflow-x: scroll;
   #carat {
     height: 10px;
     margin: 0 5px;

lib/jazzy/themes/apple/templates/doc.mustache

@@ -28,9 +28,16 @@
     {{> header}}
     <div class="content-wrapper">
       <p id="breadcrumbs">
-        <a href="{{path_to_root}}index.html">{{module_name}} Reference</a>
+        <a href="{{path_to_root}}index.html">{{readme_title}}</a>
+        {{#breadcrumbs}}
         <img id="carat" src="{{path_to_root}}img/carat.png" alt=""/>
+        {{#last}}
         {{name}} {{kind}} Reference
+        {{/last}}
+        {{^last}}
+        <a href="{{path_to_root}}{{url}}">{{name}}</a>
+        {{/last}}
+        {{/breadcrumbs}}
       </p>
     </div>
     <div class="content-wrapper">

lib/jazzy/themes/fullwidth/templates/doc.mustache

@@ -31,9 +31,16 @@
     {{> header}}
 
     <p class="breadcrumbs">
-      <a class="breadcrumb" href="{{path_to_root}}index.html">{{module_name}} Reference</a>
+      <a class="breadcrumb" href="{{path_to_root}}index.html">{{readme_title}}</a>
+      {{#breadcrumbs}}
       <img class="carat" src="{{path_to_root}}img/carat.png" alt=""/>
+      {{#last}}
       {{name}} {{kind}} Reference
+      {{/last}}
+      {{^last}}
+      <a class="breadcrumb" href="{{path_to_root}}{{url}}">{{name}}</a>
+      {{/last}}
+      {{/breadcrumbs}}
     </p>
 
     <div class="content-wrapper">

lib/jazzy/themes/jony/templates/doc.mustache

@@ -26,10 +26,17 @@
       <div class="content-wrapper">
         <p id="breadcrumbs">
           <span class="no-mobile">
-            <a href="{{path_to_root}}index.html">{{module_name}} Reference</a>
+            <a href="{{path_to_root}}index.html">{{readme_title}}</a>
+            {{#breadcrumbs}}
             <img id="carat" src="{{path_to_root}}img/carat.png" alt=""/>
+            {{#last}}
+            {{name}} {{kind}} Reference
+            {{/last}}
+            {{^last}}
+            <a href="{{path_to_root}}{{url}}">{{name}}</a>
+            {{/last}}
+            {{/breadcrumbs}}
           </span>
-          {{name}} {{kind}} Reference
         </p>
       </div>
     </div>