[WIP] Allow nested categories with recursive navigation.

lib/jazzy/config.rb

@@ -310,7 +310,12 @@ def expand_path(path)
       description: ['Custom navigation categories to replace the standard '\
                     '“Classes, Protocols, etc.”', 'Types not explicitly named '\
                     'in a custom category appear in generic groups at the end.',
-                    'Example: https://git.io/v4Bcp'],
+                    'You can add another category in the children array instead '\
+                    'of using a type name, to create subcategories.',
+                    'This can be repeated ad infinitum, provided '\
+                    'your theme supports it.',
+                    'Currently all integrated themes support a maximum of 3 levels.',
+                    'Example: https://git.io/fNvGB'],
       default: []
 
     config_attr :custom_head,

lib/jazzy/doc_builder.rb

@@ -34,18 +34,24 @@ def self.doc_structure_for_docs(docs)
         children = doc.children
                       .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
                       .flat_map do |child|
-          # FIXME: include arbitrarily nested extensible types
-          [{ name: child.name, url: child.url }] +
-            Array(child.children.select do |sub_child|
-              sub_child.type.swift_extensible? || sub_child.type.extension?
-            end).map do |sub_child|
-              { name: "– #{sub_child.name}", url: sub_child.url }
-            end
+          if child.type == SourceDeclaration::Type.category
+            doc_structure_for_docs([child])
+          else
+            # FIXME: include arbitrarily nested extensible types
+            [{ name: child.name, url: child.url, children: nil}] +
+              Array(child.children.select do |sub_child|
+                sub_child.type.swift_extensible? || sub_child.type.extension?
+              end).map do |sub_child|
+                { name: "– #{sub_child.name}", url: sub_child.url, children: nil }
+              end
+          end
         end
+
         {
           section: doc.name,
           url: doc.url,
           children: children,
+          level: doc.level,
         }
       end
     end
@@ -105,6 +111,13 @@ def self.each_doc(output_dir, docs, &block)
           doc.children,
           &block
         )
+        if doc.subsections != nil
+          each_doc(
+            output_dir,
+            doc.subsections,
+            &block
+          )
+        end
       end
     end
 
@@ -383,6 +396,26 @@ def self.render_tasks(source_module, children)
       end
     end
 
+    def self.render_subsections(subsections, source_module)
+      subsections.map do |subsection|
+        overview = (subsection.abstract || '') + (subsection.discussion || '')
+        alternative_abstract = subsection.alternative_abstract
+        if alternative_abstract
+          overview = render(subsection, alternative_abstract) + overview
+        end
+        tasks = render_tasks(source_module, subsection.children.select { |c| c.type != SourceDeclaration::Type.category })
+
+        {
+          name: subsection.name,
+          overview: overview,
+          uid: URI.encode(subsection.name),
+          url: subsection.url,
+          level: subsection.level,
+          tasks: tasks,
+        }
+      end
+    end
+
     # rubocop:disable Metrics/MethodLength
     # Build Mustache document from single parsed doc
     # @param [Config] options Build options
@@ -412,7 +445,9 @@ def self.document(source_module, doc_model, path_to_root)
       doc[:declaration] = doc_model.display_declaration
       doc[:overview] = overview
       doc[:structure] = source_module.doc_structure
-      doc[:tasks] = render_tasks(source_module, doc_model.children)
+      categories, children = doc_model.children.partition { |c| c.type == SourceDeclaration::Type.category }
+      doc[:tasks] = render_tasks(source_module, children)
+      doc[:subsections] = render_subsections(categories, source_module)
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
       doc[:github_url] = source_module.github_url

lib/jazzy/source_category.rb

@@ -0,0 +1,78 @@
+require 'jazzy/source_declaration'
+require 'jazzy/config'
+require 'jazzy/source_mark'
+require 'jazzy/jazzy_markdown'
+
+module Jazzy
+  # Category (group, contents) pages generated by jazzy
+  class SourceCategory < SourceDeclaration
+    extend Config::Mixin
+
+    def initialize(group, name, abstract, url_name, level = 1)
+      super()
+      self.type     = SourceDeclaration::Type.category
+      self.name     = name
+      self.url_name = url_name
+      self.abstract = Markdown.render(abstract)
+      self.children = group
+      self.parameters = []
+      self.mark       = SourceMark.new
+      self.level    = level
+    end
+
+    # Group root-level docs into custom categories or by type
+    def self.group_docs(docs)
+      custom_categories, docs =
+        group_custom_categories(docs, config.custom_categories)
+      type_categories, uncategorized = group_type_categories(
+        docs, custom_categories.any? ? 'Other ' : ''
+      )
+      custom_categories + type_categories + uncategorized
+    end
+
+    def self.group_custom_categories(docs, categories, level = 1)
+      group = categories.map do |category|
+        children = category['children'].flat_map do |child|
+          if child.is_a?(Hash)
+            # Nested category, recurse
+            docs_with_name, docs = group_custom_categories(docs, [child], level + 1)
+          else
+            # Doc name, find it
+            docs_with_name, docs = docs.partition { |doc| doc.name == child }
+            if docs_with_name.empty?
+              STDERR.puts(
+                'WARNING: No documented top-level declarations match ' \
+                "name \"#{child}\" specified in categories file",
+              )
+            end
+          end
+          docs_with_name
+        end
+        # Category config overrides alphabetization
+        children.each.with_index { |child, i| child.nav_order = i }
+        make_group(children, category['name'], '', nil, level)
+      end
+      [group.compact, docs]
+    end
+
+    def self.group_type_categories(docs, type_category_prefix)
+      group = SourceDeclaration::Type.all.map do |type|
+        children, docs = docs.partition { |doc| doc.type == type }
+        make_group(
+          children,
+          type_category_prefix + type.plural_name,
+          "The following #{type.plural_name.downcase} are available globally.",
+          type_category_prefix + type.plural_url_name,
+        )
+      end
+      [group.compact, docs]
+    end
+
+    def self.make_group(group, name, abstract, url_name = nil, level = 1)
+      group.reject! { |doc| doc.name.empty? }
+      unless group.empty?
+        SourceCategory.new(group, name, abstract, url_name, level)
+      end
+    end
+  end
+end

lib/jazzy/source_declaration.rb

@@ -99,6 +99,8 @@ def display_other_language_declaration
     attr_accessor :end_line
     attr_accessor :nav_order
     attr_accessor :url_name
+    attr_accessor :level
+    attr_accessor :subsections
 
     def alternative_abstract
       if file = alternative_abstract_file

lib/jazzy/source_declaration/type.rb

@@ -129,6 +129,10 @@ def self.overview
         Type.new('Overview')
       end
 
+      def self.category
+        Type.new('Category')
+      end
+
       def hash
         kind.hash
       end
@@ -150,6 +154,11 @@ def ==(other)
           dash: 'Section',
         }.freeze,
 
+        'Category' => {
+          jazzy: nil,
+          dash: 'Section',
+        }.freeze,
+
         # Objective-C
         'sourcekitten.source.lang.objc.decl.unexposed' => {
           jazzy: 'Unexposed',

lib/jazzy/sourcekitten.rb

@@ -11,6 +11,7 @@
 require 'jazzy/source_declaration'
 require 'jazzy/source_mark'
 require 'jazzy/stats'
+require 'jazzy/source_category'
 
 ELIDED_AUTOLINK_TOKEN = '36f8f5912051ae747ef441d6511ca4cb'.freeze
 
@@ -59,58 +60,6 @@ def self.undocumented_abstract
       ).freeze
     end
 
-    # Group root-level docs by custom categories (if any) and type
-    def self.group_docs(docs)
-      custom_categories, docs = group_custom_categories(docs)
-      type_categories, uncategorized = group_type_categories(
-        docs, custom_categories.any? ? 'Other ' : ''
-      )
-      custom_categories + type_categories + uncategorized
-    end
-
-    def self.group_custom_categories(docs)
-      group = Config.instance.custom_categories.map do |category|
-        children = category['children'].flat_map do |name|
-          docs_with_name, docs = docs.partition { |doc| doc.name == name }
-          if docs_with_name.empty?
-            STDERR.puts 'WARNING: No documented top-level declarations match ' \
-                        "name \"#{name}\" specified in categories file"
-          end
-          docs_with_name
-        end
-        # Category config overrides alphabetization
-        children.each.with_index { |child, i| child.nav_order = i }
-        make_group(children, category['name'], '')
-      end
-      [group.compact, docs]
-    end
-
-    def self.group_type_categories(docs, type_category_prefix)
-      group = SourceDeclaration::Type.all.map do |type|
-        children, docs = docs.partition { |doc| doc.type == type }
-        make_group(
-          children,
-          type_category_prefix + type.plural_name,
-          "The following #{type.plural_name.downcase} are available globally.",
-          type_category_prefix + type.plural_url_name,
-        )
-      end
-      [group.compact, docs]
-    end
-
-    def self.make_group(group, name, abstract, url_name = nil)
-      group.reject! { |doc| doc.name.empty? }
-      unless group.empty?
-        SourceDeclaration.new.tap do |sd|
-          sd.type     = SourceDeclaration::Type.overview
-          sd.name     = name
-          sd.url_name = url_name
-          sd.abstract = Markdown.render(abstract)
-          sd.children = group
-        end
-      end
-    end
-
     def self.sanitize_filename(doc)
       unsafe_filename = doc.url_name || doc.name
       sanitzation_enabled = Config.instance.use_safe_filenames
@@ -132,7 +81,9 @@ def self.make_doc_urls(docs)
             subdir_for_doc(doc) +
             [sanitize_filename(doc) + '.html']
           ).join('/')
-          doc.children = make_doc_urls(doc.children)
+          if doc.children.count > 0
+            doc.children = make_doc_urls(doc.children)
+          end
         else
           # Don't create HTML page for this doc if it doesn't have children
           # Instead, make its link a hash-link on its parent's page
@@ -806,7 +757,7 @@ def self.parse(sourcekitten_output, min_acl, skip_undocumented, inject_docs)
         docs = docs.reject { |doc| doc.type.swift_enum_element? }
       end
       ungrouped_docs = docs
-      docs = group_docs(docs)
+      docs = SourceCategory.group_docs(docs)
       make_doc_urls(docs)
       autolink(docs, ungrouped_docs)
       [docs, @stats]

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

@@ -320,6 +320,12 @@ pre code {
 .nav-group-tasks {
   margin: $gutter/2 0;
   padding: 0 0 0 $gutter/2;
+
+  .nav-group-name {
+    list-style-type: none;
+    border: 0px;
+    padding: 0px;
+  }
 }
 
 .nav-group-task {
@@ -332,6 +338,24 @@ pre code {
   color: $navigation_task_color;
 }
 
+@mixin nav_heading($font-size: 1.5rem, $margin: 1.0rem 0px 0px 0px) {
+  font-size: $font-size;
+  font-weight: $heading_weight;
+  margin: $margin;
+}
+
+.nav-groups {
+  h1 {
+    @include nav_heading(1.75rem);
+  }
+  h2 {
+    @include nav_heading(1.5rem);
+  }
+  h3 {
+    @include nav_heading(1.25rem);
+  }
+}
+
 // ===========================================================================
 //
 //  Content
@@ -379,6 +403,18 @@ pre code {
   padding-top: 0px;
 }
 
+.nested-tasks {
+  .task-group {
+    margin-top: 10px;
+  }
+}
+
+.nested-tasks-line {
+  border: none;
+  border-top: $gray_border;
+  margin-top: 15px;
+}
+
 .task-name-container {
   a[name] {
     &:before {
@@ -612,4 +648,4 @@ form[role=search] {
   .tt-suggestion.tt-cursor .doc-parent-name {
     color: #fff;
   }
-}
+}

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

@@ -49,7 +49,7 @@
         </section>
 
         {{> tasks}}
-
+        
       </article>
     </div>
     {{> footer}}

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

@@ -1,16 +1,7 @@
 <nav class="navigation">
   <ul class="nav-groups">
     {{#structure}}
-    <li class="nav-group-name">
-      <a class="nav-group-name-link" href="{{path_to_root}}{{url}}">{{section}}</a>
-      <ul class="nav-group-tasks">
-        {{#children}}
-        <li class="nav-group-task">
-          <a class="nav-group-task-link" href="{{path_to_root}}{{url}}">{{name}}</a>
-        </li>
-        {{/children}}
-      </ul>
-    </li>
+      {{> nav_section}}
     {{/structure}}
   </ul>
 </nav>