Group global constants and functions by the file they're in?

[thePsguy]

I see that specifyingcustom_categories can be used to achieve this, but for growing files, some that hold global constants and some that hold global functions, it is an additional maintenance overhead.

#1170 and #105 seem related, but having an option to group such symbols automatically by the file name / specifying a group at the file level would be amazing.

Is it possible to set up custom_categories using wildcards? i.e. maybe a pattern in the symbol names, or based on the file they're in?
If not, what would implementation for wildcards in custom_categories or file level grouping look like?

I believe since custom_categories is something that is already parsed and processed, adding support for wildcards or parsing files might be a smaller change?
Is it okay if I work on it?
Do we have access to the file name / source directory a symbol was in, in def self.group_custom_categories(docs)?

jazzy/lib/jazzy/sourcekitten.rb

Lines 73 to 88 in 4c0ee5d

	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?
	warn '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

Any pointers / tips would be appreciated.

eg:

"custom_categories": [{
        "name": "Global Utilities",
        "children": [
            "file:GlobalUtils.h",
            "regex:*CommonPattern*"
        ]
    }]

[johnfairh]

Yes it would be fine to add this kind of thing.

You want to be starting at this method now.

At this point, docs is an array of top-level SourceDeclarations, each a tree of source-code declarations. And doc_index is all those SourceDeclarations processed into a search tree. Here is a quick implementation of Enumerable for DocIndex -- I think you probably want to iterate over that to find your candidates.

SourceDeclaration has all the metadata in it -- name is the local name like myMethod(arg:); fully_qualified_name is the name within the declaration's module like MyClass.myMethod(arg:); fully_qualified_module_name prepends the module name if you need that.

SourceDeclaration#file is whatever SourceKit provides for the source file -- usually the fully-qualified pathname. If jazzy is in symbol graph mode though this is nil -- but your feature is still useful, just handle it gracefully & document.

For the file version I would recommend including a glob/wildcard/regexp there -- my experience is that one file is never enough for people!

You need to make sure that your output order is stable, ie. the order of the children generated is fixed for fixed input.

Happy to answer questions / review!