Allow custom_categories to define a regex or a name for each category child (#1418)

A custom category can now specify a regex for each of its children
by using an object with a regex key instead of just a string
to find all of the declaration matching that regex.

For example:
```
custom_categories:
  - name: some_category_name
    children:
    - some_exact_name
    - regex: some_regex
```

Will create a category containing:
- the declaration "some_exact_name" (if it's found)
- all the declaration that match the "some_regex" regex. (e.g. "some_regex", "some_regex1", ...)

Add custom_categories documentation in readme

Author: Enricoza

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
 

README.md

@@ -453,7 +453,19 @@ like _Classes_ and _Structures_ corresponding to programming-language concepts,
 as well as _Guides_ if `--documentation` is set.
 
 You can customize the categories and their contents using `custom_categories` in
-the config file — see the ReSwift [docs](https://reswift.github.io/ReSwift/) and
+the config file. `custom_categories` is an array of objects.  Each category must contain two properties:
+- `name`: A string with the name you want to give to this category
+- `children`: An array used to specify the root level declarations that you want to add to
+this category. 
+
+Each child, then, can be one of the following:
+- A string, containing either the exact name of one root level declaration you want to
+match, or the fully qualified name (`ModuleName.DeclarationName`)
+- An object, containing the property:
+  - `regex`: a string which will be used to match multiple root level declarations from
+all of the modules.
+
+See the ReSwift [docs](https://reswift.github.io/ReSwift/) and
 [config file](https://github.com/ReSwift/ReSwift/blob/e94737282850fa038b625b4e351d1608a3d02cee/.jazzy.json)
 for an example.
 

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, _| name.match(regex) }
+          .map { |_, 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 { |_, 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,29 +49,39 @@ 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 = select_docs(doc_index, selector)
+          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
-
-          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.compact
+        end.flatten.compact
         # 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.select_docs(doc_index, selector)
+      if selector.is_a?(String)
+        unless single_doc = doc_index.lookup(selector)
+          warn 'WARNING: No documented top-level declarations match ' \
+            "name \"#{selector}\" specified in categories file"
+          return []
+        end
+        [single_doc]
+      else
+        doc_index.lookup_regex(selector['regex'])
+          .sort_by(&:name)
+      end
+    end
+
     def self.group_guides(docs, prefix)
       guides, others = docs.partition { |doc| doc.type.markdown? }
       return [[], others] unless guides.any?