jazzy
jazzy copied to clipboard
realm
Group top-level declarations by folder structure
I'm looking into using Jazzy to document an app, and it sure would be nice to split the lefthand menu into logical groups like the folder structure of the app. It's not that helpful to see the app delegate in the same view as the models and view controllers.
I'm not sure what this feature would look like... An inline directive for jazzy in the comment? A command line argument that looks for folder names?
It would be awesome to parse the project's directory structure to group top-level declarations together. This would have to be type-agnostic (functions, classes, enums, structs, etc.) rather than just for classes.
Depending on the project (e.g. app vs library), the menu on the left might be better structured or flat. Perhaps both should always be available by toggling a switch in the docs' UI? Or maybe there should be a command line argument to explicitly specify to use directory structure like you mentioned.
Do you have any further thoughts as to how this might work, @luketheobscure?
We'd have to determine how arbitrarily-deep nested subfolders are handled. Given how little horizontal space there is in the current design, this could be tricky.
In my use-case, grouping everything by folder would make a lot of sense. You can see the generated documentation for the app I'm working on here. Without the context of the "Model" folder, it's a little hard to know what some of the classes do. Once the inheritance tree is implemented, it will be a little bit easier, but having the folders show up would be rad.
Custom Categories (#281) provide a way to control the grouping in the sidebar, which can be used to mirror the folder structure of a project, but is much more flexible than that.
ReSwift's docs uses this to great effect IMO:
- jazzy configuration file for
custom_categories: https://github.com/ReSwift/ReSwift/blob/3.0.0/.jazzy.json#L13-L63 - Output: http://reswift.github.io/ReSwift/master/
However, that's not the same as offering a mode that automatically does this without the need to maintain custom_categories entries in the jazzy config file, which is why this ticket is still open.
No work has been done to do this automatically AFAICT.
Sounds good to me. I think the current functionality is a good middle ground for now. We can leave this feature on the back burner and (when we get around to it), write up a road map that could include this automatic functionality at a future time.