Content Structuring

[Aiosa]

Is your feature request related to a problem? Please describe.

Lovely theme, but I am missing structuring options, or at least I didn't find any. For a lot of content, the menu might become too cluttered. Also, what about documenting different parts of the system?

Describe the solution you'd like

I would like to have the option to create hierarchical menus so that when I have nested namespaces, these would appear nested (under an expandable super menu for example) under their parent.
I am also having multiple abstractions ('plugins' ~ apps, 'modules' ~ libraries) and I would like to have them documented too within the page, but with separate menu, something like

Classess               >
Namespaces             >
  | -- ParentNamespace > 
      | -- Child
Global                 >
________________________

Plugins*               >
Modules*               >

With Modules* and Plugins* are essentially different sources, sets of scripts documented separately, possibly with references to the default, 'main' set of scripts (context) or with references across all the sets (contexts). Plugins can naturally use Modules and all of them use the main interfaces...

Describe alternatives you've considered

Modules and different 'taxonomies' in jsdoc.

Is there something like this possible? Thank you.

[github-actions]

Wonderful, you have created your first issue for clean-jsdoc-theme. Someone will talk to you soon!

[ankitskvmdam]

We do have hierarchical menu (but only one level deep. In [email protected] we have up to 2 level deep.) Having collapsible/expandable components more than one will increase the width of the sidebar, hence the support was dropped in

clean-jsdoc-theme >= v4

Also, we have a super convenient/smart search, which kind of remove the dependency of using sidebar.

We do have option to add and excluded section from the sidebar: https://github.com/ankitskvmdam/clean-jsdoc-theme#sections

[Aiosa]

Also, we have a super convenient/smart search, which kind of remove the dependency of using sidebar.

That's sad to hear, IMHO it does not. First, you have to know what you are looking for in order to be able to search. Check location vs exploration tasks in data visualization terminology. If you just want to get familiar with API and do not know where to start you need the menu. And you need to have it simple, with hierarchical ordering so that you do not start reading details on some service worker as the first thing in the docs.

We do have option to add and excluded section from the sidebar: https://github.com/ankitskvmdam/clean-jsdoc-theme#sections

We probably misunderstood each other, I meant to have a completely separated, custom set of documentation in its own menu, documented 'separately', but yet, be allowed to follow the smart links. Basically running jsdoc with several definitions of
source without having to explicitly define some @metadata property on every single line for these different contexts.

Classess               >
Namespaces             >
  | -- ParentNamespace > 
      | -- Child
Global                 >
________________________

Plugins*               >
 | -- MyCustomPlugin   >
    | -- Classes       >
    | -- Namespaces    >
    | -- Global        >
 | -- DifferentPlugin  >
    | -- Classes       >
    | -- Global        >

Yeah, menu levels can get pretty deep. But the other option is to have a linear list of useless names one can search through only using Ctrl+F. But I guess such flexibility is even out of JSDoc's abilities.

A different option would be to build separated documentation for each of those modules and plugins, but I would need to allow a custom smart link navigation from any plugin to any module, from any module to any other module, and from all to the core system. Would this be somehow possible?

[starlingjon]

better-docs handles this pretty well with @category and @subcategory tags, perhaps something like that could be done here?

the search feature is very useful and is the main reason i want to use this instead of better-docs (in addition to this looking better imo) but when you only have a rough idea of what you're looking for (or as Aiosa pointed out are familiarising yourself with the API) that hierarchical sidebar is a must.

tbf this is a hole in jsdoc itself but it really would make this theme perfect if it helped plug that hole :)

[rashadatjou]

I wanted to add this feature on to the VideoJS docs website. videojs/video.js#8893 explain the issue in detail. Not being able to have @subcategories when listing Events in the VideoJS docs is really confusing as seen here https://docs.videojs.com/.

I would be willing to help to get this feature out and about but I am not sure on where to start. Could anyone point me to the right direction here.

Thank you!

[ankitskvmdam]

@rashadatjou That's great!

you need to start from here: https://github.com/ankitskvmdam/clean-jsdoc-theme/blob/master/publish.js#L421 We are using this function to build the sidebar.

Also, we had this feature upto v3.3.0 for reference you can take a look at this function: https://github.com/ankitskvmdam/clean-jsdoc-theme/blob/v3.3.0/publish.js#L563

Thanks!