Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Custom categories from code comments #1170

Open
FabienLydoire opened this issue Apr 8, 2020 · 5 comments
Open

Custom categories from code comments #1170

FabienLydoire opened this issue Apr 8, 2020 · 5 comments

Comments

@FabienLydoire
Copy link
Contributor

Hello !
I'm wondering if it is possible to create categories and mark classes, strucs, enum... in those categories from comments in the code.

I do not want to maintain a list of custom categories in the jazzy configuration file : the maintenance price is too high.

I would image something like

/// MyClass documentation
/// Category: MyCategory
class MyClass {
}
@johnfairh
Copy link
Collaborator

johnfairh commented Apr 8, 2020

Yes I think this is doable -- I would go with syntax like - docs-category: MyCategory to fit in with the callout convention, this will also hide it in Quick Help. Can offer some tips on where to start if someone wants to implement it.

@nolan-yoo-miris
Copy link

Hey - I know this is old, but I wanted to bump this as something like this would be useful for our use case.

I don't know if we have the bandwidth to assist with implementation, but I'd still be interested in what the pointers would look like.

@johnfairh
Copy link
Collaborator

Broadly, without thinking too hard about it:

  • The requirement here seems to be to discover a category/article tree akin to that provided by the config file custom_categories while the source declarations are parsed, then to use that tree instead of (in addition to?) the config file's tree
  • May as well spin up a new file to hold the discovered category tree and work on it, pull any code dedicated to custom categories into here
  • Detect category paths when processing a declaration --- either using a custom doc comment as described above, or, in space year 2023, the @_documentation(metadata:) attribute which is intended for purposes like this. Either way, pull it out in make_doc_info
  • Either store the the category tree in exactly the same format as the config file would produce, or provide a getter to massage the tree into that format, and use it instead of the config file version in group_custom_categories.

@nolan-yoo-miris
Copy link

nolan-yoo-miris commented Sep 9, 2023

Thanks @johnfairh - having that on paper will be useful in case we find bandwidth to contribute.

An additional follow-up: any early design decisions on how this "might" function with #624 / #982? (IE - I think if possible, nested categorization should go in first, but I imagine you have an idea on how that might affect the implementation here.)

@johnfairh
Copy link
Collaborator

They're independent - just need the design for category paths here to allow for multiple levels, eg. @_documentation(metadata: "jazzy-category:Main/Sub/Subsub").

IIRC the thing blocking the nested category stuff is design/theme work for the left nav.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants