KDAB/knut

Refactor doc generation

Closed this issue · 4 comments

narnaud commented

Refactor the way we are generating the documentation. Right now, cpp2doc is called at every compilation, which is a waste of time, specially if there are no changes.

What we would like is:

  • remove cpp2doc from the ALL target (need explicit call)
  • only call cpp2doc during a release, to ensure everything is up to date (doesn't prevent from updating the doc manually)

I wonder what would be the best way to handle that, but surely running cpp2doc every time is a waste of resources.

LeonMatthesKDAB commented

Hm, I guess it would be ideal if cpp2doc recorded timestamps, so that it would only update the files that actually changed.

I'm honestly not a fan of only updating the docs on releases or manually. Especially as we're now deploying the docs automatically, always keeping them up-to-date would be nice.

narnaud commented

@LeonMatthesKDAB The biggest issue is that QtCreator build is failing due to doc2cpp. That's because it is unable to run the executable, even if you have Qt in the PATH (bug reported, at the bottom of the pile though).

The reason why I moved to VSCode, but still that's a pain. It's also failing due to ksyntaxhighlighting, but at least it's compiled once and that's it. But due to the cpp2doc target, it's always failing all the time.
I wonder what would be the best way to mitigate everything... maybe change my mind and go back to calling cpp2doc all the time, and let QtCreator devs handled it themseves?

LeonMatthesKDAB commented

Oh that's strange and indeed an issue...
I guess we could just provide CMake flag to disable running cpp2doc though.
Then everyone else can enable it and the people using Qt creator can leave it out?

narnaud commented

Yes, that's probably the best fix for now on.
Another idea would be to run that as part of release-please, but I have no ideas if it's even possible... that would mean updating the documentation only after a release, not ideal (I like having the documentation following the code, makes it easier to also edit/test the documentation).

So let's go with that:

  • re-add cpp2doc in the all build by default
  • add an option to deactivate it

A third task would be to optimize cpp2doc: check if the md file timestamp is higher than the cpp one, and if so do not update the documentation.