Add ability to exclude specific branches from navigation tree

[ajesshope]

Search Terms

large number of interfaces and/or classes
slow documentation generation

Problem

The generation of the navigation tree takes a very long time when there are a large number of interfaces/classes in one file. A tsc compilation takes <15secs... yet the rendering of the doco is taking ~35min. The vast majority of this time is taken by the rendering of the navigation tree for every page (makes every page about 2mb). We have a d.ts file that contains just shy of 9000 interfaces (~85k lines... essentially different database record layouts).

We did notice that if we split those interfaces across multiple files (1.25k lines each) then we can get the doco generation time down to ~2min. Though this splitting causes many more files to be listed on the navigation tree making it less useful. This does also raise the question why there is such a huge time difference when generating the doco for the same number of interfaces across multiple files versus all the interfaces in one file.

We know there is a typedoc.json 'navigation' property called 'fullTree' which can be set to false (and we have done this)... in the end this did not make the generation time any faster.

Suggested Solution

In typedoc.json add a 'navigation' property called something like 'excludeBranches' (string array) that will enable the developer to enter filenames (without the extension) to be interrogated in navigation.tsx ('navigation->links' method... property mod.name) to exclude child branches for the specified file. The file name still appears in the navigation and is selectable... it just cannot be expanded in the navigation pane. For us this cuts the page sizes from ~2mb per page to ~20k and the doco generation time reduced from ~35min to ~35secs.

[Gerrit0]

Yikes, that's a lot of interfaces... I think this makes sense to do, even with upcoming efficiency improvements for navigation, as that many navigation elements probably makes the tree not very useful to begin with.

[Gerrit0]

I just published version 0.25.1, I'm curious if the navigation changes in that release solves the performance issue before doing this

[ajesshope]

I just published version 0.25.1, I'm curious if the navigation changes in that release solves the performance issue before doing this

hi @Gerrit0
The dynamic build of the navigation is good... large reduction of time... ~35min -> ~45 seconds... thank you :)

The new "excludeCategories" (for us) does not address the enhancement request. It appears that the excluded categories are excluded from the typescript compilation (which as you may guess causes compilation errors)... I may be completely wrong with this.

The enhancement request was to exclude from the navigation only... we also would like to exclude categories 'by file' from the navigation... not just individual components. As it currently stands we'd need to list all ~8800 entries in typedoc.json under "excludeCategories" ... and this causes the same number of warnings to be written to the console about "not included in the documentation"... so another ~8800 entries to typedoc.json under "intentionallyNotExported" to suppress the warnings.

[Gerrit0]

excludeCategories was for a completely different feature request - #1407 :)

I was mainly curious if this was still useful with the dynamically loaded navigation, it seems like it is, so will likely be included in the next release