jazzy
jazzy copied to clipboard
realm
support nested custom_categories
Asking for support of nesting custom_categories: For example:
custom_categories:
- name: Classes
children:
- name: Bar Type
children:
- RealmBarData
- RealmBarDataSet
- name: Protocols
children:
- name: BarDataProtocol
children:
- RealmBarDataProtocol
- RealmBarDataSetProtocol
Hi @liuxuan30. We'll consider this as a feature request but we currently do not have the bandwidth to implement it ourselves. However, we would happily review a PR if you can implement this and file one. Cheers!
I will gladly implement this. Before I throw myself at the problem, do you think it would make sense to use recursion? i.e. allow the "user" to specify as much nested categories as they want and then have the themes use a recursive nav partial?
@justinmkaufman slow but steady. To help us out are you able to share how you would use it (eg. how many levels, what jazzy theme you're using...)
@JUSTINMKAUFMAN Additionally, please take a look on my pr and leave some feedback on whether this would solve your use case.
Thanks for the quick responses!
@johnfairh My only pain point with Jazzy is the amount of configuration required to get the produced documentation organized in a way that is meaningful in the context of my project (i.e. not just an enormous list of alphabetized classes/protocols/etc.).
What would make Jazzy an indispensable tool for my use cases would be a parameter along the lines of --categorize_by_group.
When enabled, this would cause Jazzy to parse my project's directory structure and automatically create custom categories based on the names of the folders/groups in which files reside. Top-level declarations found inside a folder/group would produce documentation inside the corresponding category, and subfolders/subgroups would produce nested categories.
For example, from this project:
Jazzy would produce the following category structure (and enclose the pertinent documentation) automatically:
custom_categories:
- name: Tokens children: - name: App Control
- name: Storyboards
- name: Strategy children: - name: Bots
- name: Models
- name: Views
- name: Controllers children: - name: Common
- name: Managers
- name: Supporting Files children: - name: Extensions - name: Miscellaneous
@galli-leo I have actually installed your fork containing the PR you referenced, thanks for working on this! Unfortunately I got stuck while trying to further customize sourcekitten.rb to make it match declaration names on string prefixes (i.e. if I have numerous classes that all start with the word Home - e.g., HomeButtons, HomeInputs, HomeRouter, etc. - then it would automatically put all of those declarations under the Home category).
I didn't spend too much time on this, and this was my first time dabbling in ruby, so I'm sure I just fumbled the code. This is where I left off (line ~79):
def self.group_custom_categories(docs, categories = nil, level = 1)
categories ||= Config.instance.custom_categories
group = categories.map do |category|
children = category['children'].flat_map do |child|
if child.is_a?(Hash)
docs_with_name, docs = group_custom_categories(docs, [child], level + 1)
docs_with_name
else
# docs_with_name, docs = docs.partition { |doc| doc.name == child }
docs_with_name, docs = docs.partition { |doc| doc.name.start_with?(child) }
if docs_with_name.empty?
STDERR.puts 'WARNING: No documented top-level declarations start with ' \
"name \"#{child}\" specified in categories file"
end
docs_with_name
end
end
# Category config overrides alphabetization
children.each.with_index { |child, i| child.nav_order = i }
subsections, children = children.partition { |c| c.type == SourceDeclaration::Type.overview }
make_group(children, category['name'], '', nil, level, subsections)
end
[group.compact, docs]
end
Any help getting this working would be greatly appreciated!
Thanks.
OK - see #105 for the filesystem thing but yes we need this multi-level part first.
Your code is saying "when I see a string object in a children array then instead of grabbing a type that matches exactly, grab all types with that prefix". It works fine. Your goal of "create a section and populate it" is more complicated. I would just swallow the redundancy:
custom_categories:
- name: Home Things
children:
- Home
... will grab all types starting "Home".
Yeah file system should be relatively easy to implement after this. Just use the folders instead of the custom_categories.
@galli-leo Is there a way to automate this now with just top-level folders (ignoring nested)?
Just stumbled on this -- Implementing Jazzy Docs here for an iOS chart component. So nested categories, that would be really useful!
Could we (the scichart team) help to do this as well? Who's made any progress or got stuck or has ideas how to do it?
@andyb1979 I rebased the jf-nested-dev branch that took pieces of code and lots of learning from #982 and the core function looks to basically work.
The biggest remaining piece that I'm not sure how to tackle is theme updates to let the sidebar resize/scroll horizontally; also grateful for any improvements on how the nav sidebar is constructed/styled/rendered --- I just did the simplest thing of continuing to nest lists....
This would be an awesome feature to have! I am looking for something similar to @JUSTINMKAUFMAN
I am still looking for this feature, too. Would it make sense to just have a flag to use the default folder hierarchy, instead of defining it as well? I think it would serve a great purpose if I wouldnt have to specify where my hundreds of files have to go in the documentation if I can just use the same skeleton as my project...
Still waiting for a fix of this issue. If there's a workaround possible, please let us know.
