diff --git a/CHANGELOG.md b/CHANGELOG.md index 92bfec61c..d64ce4943 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/lib/jazzy/config.rb b/lib/jazzy/config.rb index 54a0deca9..d128b9d75 100644 --- a/lib/jazzy/config.rb +++ b/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 diff --git a/lib/jazzy/doc_builder.rb b/lib/jazzy/doc_builder.rb index 7bdd0927a..b7e4b7eca 100644 --- a/lib/jazzy/doc_builder.rb +++ b/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 diff --git a/lib/jazzy/source_declaration.rb b/lib/jazzy/source_declaration.rb index 7578bbb52..c07fef27b 100644 --- a/lib/jazzy/source_declaration.rb +++ b/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 diff --git a/lib/jazzy/source_document.rb b/lib/jazzy/source_document.rb index 1cb3b4bc1..f2bc4e113 100644 --- a/lib/jazzy/source_document.rb +++ b/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 diff --git a/lib/jazzy/source_module.rb b/lib/jazzy/source_module.rb index 18f2f9963..f4c3fe69c 100644 --- a/lib/jazzy/source_module.rb +++ b/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) diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb index f2417dfda..8c99158e5 100644 --- a/lib/jazzy/sourcekitten.rb +++ b/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 diff --git a/lib/jazzy/themes/apple/assets/css/jazzy.css.scss b/lib/jazzy/themes/apple/assets/css/jazzy.css.scss index 6f5fa0d70..d83b102e4 100644 --- a/lib/jazzy/themes/apple/assets/css/jazzy.css.scss +++ b/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; diff --git a/lib/jazzy/themes/apple/templates/doc.mustache b/lib/jazzy/themes/apple/templates/doc.mustache index 41337ce96..534fbc115 100644 --- a/lib/jazzy/themes/apple/templates/doc.mustache +++ b/lib/jazzy/themes/apple/templates/doc.mustache @@ -28,9 +28,16 @@ {{> header}}
diff --git a/lib/jazzy/themes/fullwidth/templates/doc.mustache b/lib/jazzy/themes/fullwidth/templates/doc.mustache index 4d7955c47..ca657acae 100644 --- a/lib/jazzy/themes/fullwidth/templates/doc.mustache +++ b/lib/jazzy/themes/fullwidth/templates/doc.mustache @@ -31,9 +31,16 @@ {{> header}}
diff --git a/lib/jazzy/themes/jony/templates/doc.mustache b/lib/jazzy/themes/jony/templates/doc.mustache index b5a4d8a3d..195a58978 100644 --- a/lib/jazzy/themes/jony/templates/doc.mustache +++ b/lib/jazzy/themes/jony/templates/doc.mustache @@ -26,10 +26,17 @@
diff --git a/spec/integration_specs b/spec/integration_specs index 81cf15d0d..a00823227 160000 --- a/spec/integration_specs +++ b/spec/integration_specs @@ -1 +1 @@ -Subproject commit 81cf15d0d42e5aba56ff0624ee980bad16306700 +Subproject commit a0082322748fbb6847ccb20b3ad509b9cf62292a