Add category tag

[jonchardy]

In reference to #564. We did some custom work to add an @category tag in our build, so I figured I'd share it here. Feel free to change this as needed.

Basically, it works by looking through tags in a reflection's comment and building up a list of reflections that belong to each category in a similar manner to the way reflections are grouped by their kind (Method, Accessor, Property, etc.).

Also note, it won't really do much without some accompanying changes to a theme, but you can see some sample output if you use the JSON output option.

We mostly use this in file mode at the class level, so that's what it will work best for and I don't know how well it will work for other uses. I suppose this PR can be expanded upon if the scope needs to increase based on people who want the feature.

[dupski]

+1 I'd love to see this merged. A lack of class categories makes the generated docs pretty hard to use for larger modules.

[blakeembrey]

@jonchardy Let me know if there's anything else needed or docs that can be improved to tell people how they can use this. Is there a theme update or anything else recommended?

[jonchardy]

Sure. So there are some things that should be set up to use this effectively:

1. Add @category tags within docstrings for classes. Classes without categories will be given a category of ''. This can be customized pretty easily by changing the getCategory method in CategoryPlugin.ts.

/**
 * Class description.
 *
 * More detailed info about class.
 * @category SomeCategory
 */
export class Foo {
  ...

2. Use the "file" output mode.
3. Customize typedoc-default-theme to use the category information that is output by Typedoc. We adjusted our index to divide the classes up by category, so our typedoc-default-themes\src\default\partials\index.hbs looks like this:

{{#if categories}}
    <section class="tsd-panel-group tsd-index-group">
        <h2>Index</h2>
        <section class="tsd-panel tsd-index-panel">
            <div class="tsd-index-content">
                {{#each categories}}
                    <section class="tsd-index-section">
                        <h3>{{title}} Classes</h3>
                        <ul class="tsd-index-list">
                            {{#each children}}
                                <li class="{{cssClasses}}"><a href="{{relativeURL url}}" class="tsd-kind-icon">{{#if name}}{{{wbr name}}}{{else}}<em>{{{wbr kindString}}}</em>{{/if}}</a></li>
                            {{/each}}
                        </ul>
                    </section>
                {{/each}}
            </div>
        </section>
    </section>
{{else}}
    {{#if groups}}
        <section class="tsd-panel-group tsd-index-group">
            <h2>Index</h2>
            <section class="tsd-panel tsd-index-panel">
                <div class="tsd-index-content">
                    {{#each groups}}
                        <section class="tsd-index-section {{cssClasses}}">
                            <h3>{{title}}</h3>
                            <ul class="tsd-index-list">
                                {{#each children}}
                                    {{!-- only output external modules that have children, not empty ones --}}
                                    {{#ifCond kindString "==" "External module"}}
                                        {{#if children}}
                                            <li class="{{cssClasses}}"><a href="{{relativeURL url}}" class="tsd-kind-icon">{{#if name}}{{{wbr name}}}{{else}}<em>{{{wbr kindString}}}</em>{{/if}}</a></li>
                                        {{/if}}
                                    {{else}}
                                        <li class="{{cssClasses}}"><a href="{{relativeURL url}}" class="tsd-kind-icon">{{#if name}}{{{wbr name}}}{{else}}<em>{{{wbr kindString}}}</em>{{/if}}</a></li>
                                    {{/ifCond}}
                                {{/each}}
                            </ul>
                        </section>
                    {{/each}}
                </div>
            </section>
        </section>
    {{/if}}
{{/if}}

Of course, people are going to want to customize their theme to use categories in different ways.

Hope this helps, not sure where the best place is to document it.

[bbugh]

Is this possible to use in the table of contents? I can't find any "top level" way to get the categories - unless it's in #with model, it's always undefined. Looking for something like toc that has the top level categories on all pages.