Group summary pages?

[sporritt]

Search Terms

group groupDescription category

Problem

I've recently started using @group and @category, which have helped me organise the docs a lot better. I arrange by group in the index so I get the collapsing menus and it's all good.

The main page lists out the contents of each group in order, and I was hoping for the ability to click on group names in the nav column and be taken to a summary page for that group, which would have the @groupDescription tag and then all of the group's members. Does this exist and I have just failed to find it? I see that the group description is being included in the json output.

Suggested Solution

An output config like includeGroupSummaryPages:boolean ?

[Gerrit0]

See #2793, TypeDoc 0.28's rework of the router has made it easier for custom themes to do this, but it isn't supported by the default theme. My concerns raised there are still present:

Doing this raises a lot of questions... can you @link to those pages? What does the current module page look like then, does it contain duplicate information or links to the category pages, basically making it useless? What about groups, do they get their own pages? What if categorizeByGroup is true and the site includes both categories and groups, how does linking work then? Do you get a page per group and per category, or per group+category? Allowing this would require a major architecture change on the order of adding support for @document as TypeDoc expects pages to be generated according to reflection children, which this breaks entirely... not saying it can't happen, just that it isn't an easy change...

[sporritt]

Thanks for replying. I'll give my own naive answers to your questions - but of course I know nothing of the larger considerations!

can you @link to those pages?

Ideally, yes, although admittedly I hadn't thought of this as a requirement until seeing this question. My use case is the api docs for JsPlumb, and I'm using groups to define things like Events, CSS Classes, Components - top level concepts. Then categories for me are effectively sub groups - "CSS classes used by the Surface component", "Events fired by the model", "Events fired by the UI", etc. So linking to the page where all the CSS Classes are listed, by category, would be useful.

What does the current module page look like then, does it contain duplicate information or links to the category pages, basically making it useless?

I must confess that the concept of module is rather hazy to me. I don't have a @module tag declared anywhere in my TS files. Does it basically map to the entry point? I have @packageDocumentation in my entry point index.ts, along with a bunch of @groupDescription tags.

What about groups, do they get their own pages?

I think this is what I'm requesting - I'd like each group to have its own page, with categories listed in sections.

What if categorizeByGroup is true and the site includes both categories and groups, how does linking work then? Do you get a page per group and per category, or per group+category?

I do have categorizeByGroup set, it's a key part of how I'm arranging the docs. Page per category strikes me as something that would be cool, but can a category "belong" to more than one group? And if so how would that page be put together. In fact I suspect that my mental model of category being a kind of sub-group is not how Typedocs sees things.

Looking through the generated JSON I can see that the data structure would support the generation of a group+categories page, for example:

{
  id:0,
  name:"JsPlumb",
  ...
  groups:[
     {
       title:"CSS Classes",
       categories:[
          {
            title:"Background plugin",
            children:[
                   245, 575, 1937
            ]
         }, ....
        ]
    }, ....
  ]
}

...all of the information required to assemble the type of page I'm asking about is available, and the groups are children of the root, suggesting that it would be possible to have a unique page for each one without namespace clashes. Since the internal model can write out this JSON I guess it could also be made to write out an HTML page for each group. Categories, though, don't seem quite so straightforward.

[Gerrit0]

can you @link to those pages?

To expand on this -- how? TS and VSCode know nothing about TypeDoc's groups, so it would be a TypeDoc specific link resolution.

/**
 * @groupDescription Events
 * **FooEvent** - ...
 */

/** @group Events */
export class FooEvent {}

/** @group Events */
export class BarEvent {}

/** @group Events */
export type Events = FooEvent | BarEvent;

/** See {@link Events} for details on each event */
export function emit() {}

TypeScript will understandably link @link Events to the type alias... Extending the meaning part of declaration references would probably work... {@link !:group(Events)}

I must confess that the concept of module is rather hazy to me

Your intuition is correct that it roughly maps to an entry point, with the exception of the packages and merge entryPointStrategy options. Currently, it's the page which includes the @groupDescription for each of your members.

Group summary pages would likely be limited to modules (and maybe namespaces?). Classes, interfaces, and type aliases might also have groups within them, but if those are so big as to need splitting up, something has gone horribly wrong.

Page per category strikes me as something that would be cool, but can a category "belong" to more than one group?

Yes, without any group tags if categorizeByGroup is true, @category Foo on a function and an interface, would result in Interfaces > Foo and Functions > Foo as the contained categories. If categorizeByGroup is false, then if @category is used for a children of a container, then the categories will be Foo (and probably Other, the defaultCategory default option value)

If categorizeByGroup is not set, TypeDoc also won't run categorization within groups, so the Functions group will have all the functions, no matter how @category is set. When rendering TypeDoc will use categories if possible, then fall back to groups, using their categories if set, otherwise using their children directly... it's rather confusing without the code pulled up. (https://github.com/TypeStrong/typedoc/blob/182ef52e09757138009bbf5d724c08de0d017a9a/src/lib/output/themes/lib.tsx#L208-L249)