Typedoc: Incremental build support

[ghost]

Just like TypeScript can support incremental builds, I was wondering if TypeDoc is able to do the same thing. If not, I am wondering what it would take to implement this.

[blakeembrey]

I'm not aware of it, hopefully someone else could chime in. It's not really the kind of project I'd suspect a need for incremental builds. You could use something like onchange to detect changes and re-compile too.

[basarat]

It's not really the kind of project I'd suspect a need for incremental builds

Agreed. For incremental builds you would probably also want _link to live source_. I'm actually working on something like this for my IDE https://github.com/alm-tools/alm/issues/78#issue-154976324 :rose:

[unsafecode]

+1 Definitely something to support, especially for large codebases

[blakeembrey]

@unsafecode Can you elaborate? Why would generate documentation often instead of once to necessitate a watch mode?

[unsafecode]

@blakeembrey Sure: I'm currently working on a large project, and we need to integrated the docs quickly, by taking a look at each change we make. Rebuild all the item after every edit or so is very time consuming, so instead I was wondering whether it might be possibile to watch only for changed files and get immediate feedback.

[aciccarello]

@unsafecode I still don't understand your workflow.

Generally, I think of the documentation outputted by TypeDoc as a reference for someone coming to a project. For example, the ui-router project has documentation for those using that library. But I tend to think that if you are actively developing the codebase you should be able to use IDE tools like Intellisense in VS Code on opening other files to understand how your code works.

[unsafecode]

@aciccarello In our case, the customers expects all the technical documentation to be part of our CI process, so we need to review and integrate the information often (kind of daily, or weekly at best). Lately, I've been spending quite some time improving our TS docs and I've found that rebuild them from scratch every time is very time-consuming.

[mani-vandrangi]

@blakeembrey @aciccarello Any idea when this will be available.

[Gerrit0]

Supporting this is incredibly difficult if done right. It requires:

1. Providing a 1-1 serialization/deserialization output so that instead of re-analyzing code we can pull the relevant information from the cache. (The JSON output does not support this)
2. Determining (quickly) if changes to the code require changes to the documentation. (Even TypeScript's support for incremental builds is far from bug free, this is probably the hardest part)
3. Keeping track of everywhere that a reference is used, and re-rendering only those pages when that reference is updated. (With the current setup for themes, this isn't possible)

---

Additionally, TypeDoc isn't worked on full time (or even part time) by anyone. Any progress is made when someone has time to work on an open source project and chooses TypeDoc. Personally, I think there are quite a few other issues which are more urgent than this one, so I won't be pursuing this in the foreseeable future. If someone from the community wants to take a shot at it, go ahead!

[Gerrit0]

Not all the way there - but #1482 adds support for --watch, which takes advantage of TypeScript's incremental type checking. I still stand by my original statement that true incremental support is really hard.