Allow custom_categories to define a regex or a name for each category child

CHANGELOG.md

@@ -6,7 +6,9 @@
 
 ##### Enhancements
 
-* None.
+* Allow `custom_categories` to specify a regex for a child.
+  [Enrico Zannini](https://github.com/Enricoza)
+  [#688](https://github.com/realm/jazzy/issues/688)
 
 ##### Bug Fixes
 

lib/jazzy/doc_index.rb

@@ -64,6 +64,12 @@ def lookup(parts)
         children[parts.first]&.lookup(parts[1...])
       end
 
+      # Look up of a regex matching all children for current level only.
+      def lookup_regex(regex)
+        children.select { |name, scope| name.match(regex)}
+          .map { |name, scope| scope.decl }.compact
+      end
+
       # Get an array of scopes matching the name parts.
       def lookup_path(parts)
         [self] +
@@ -90,6 +96,11 @@ def lookup(name, context = nil)
       lookup_context(lookup_name, context)
     end
 
+    # Look up a regex and return all matching top level SourceDeclaration.
+    def lookup_regex(regex)
+      root_scope.children.map { |name, scope| scope.lookup_regex(regex) }.flatten
+    end
+
     private
 
     # Look up a fully-qualified name, ie. it starts with the module name.

lib/jazzy/grouper.rb

@@ -49,22 +49,29 @@ def self.group_docs_by_module(docs, type_category_prefix)
 
     def self.group_custom_categories(docs, doc_index)
       group = config.custom_categories.map do |category|
-        children = category['children'].map do |name|
-          unless doc = doc_index.lookup(name)
-            warn 'WARNING: No documented top-level declarations match ' \
-              "name \"#{name}\" specified in categories file"
-            next nil
+        children = category['children'].map do |selector|
+          selected = if selector.is_a?(String)
+            unless doc = doc_index.lookup(selector)
+              warn 'WARNING: No documented top-level declarations match ' \
+                "name \"#{name}\" specified in categories file"
+              []
+            else
+              [doc]
+            end
+          else
+            doc_index.lookup_regex(selector['regex'])
+              .sort_by { |doc| doc.name.downcase }
           end
-
-          unless doc.parent_in_code.nil?
-            warn "WARNING: Declaration \"#{doc.fully_qualified_module_name}\" " \
-              'specified in categories file exists but is not top-level and ' \
-              'cannot be included here'
-            next nil
+          selected.map do |doc|
+            unless doc.parent_in_code.nil?
+              warn "WARNING: Declaration \"#{doc.fully_qualified_module_name}\" " \
+                'specified in categories file exists but is not top-level and ' \
+                'cannot be included here'
+              next nil
+            end
+            docs.delete(doc)
           end
-
-          docs.delete(doc)
-        end.compact
+        end.flatten.compact
         # Category config overrides alphabetization
         children.each.with_index { |child, i| child.nav_order = i }
         make_group(children, category['name'], '')