Update TypeDoc #1090
Update TypeDoc #1090
Conversation
This required changing the build setup to use our wireit. From a spot check this will need more work as some debug only symbols have crept into the documentation.
The cost does not seem worthwhile for fixing this and blocking progress on Lit.dev support for v3. Instead unblock by manually providing the transpiled JavaScript for the Mixin sample.
This is due to a breaking change in TypeDoc. Default `entryPointStrategy` was changed from `expand` to `resolve`. Fixed by explicitly setting the prior version.
This fixes the source file links.
Co-authored-by: Augustine Kim <[email protected]>
The most major change that impacts our documentation generation is the `Comment` node has been updated to be a list of partial text fragments. We instead used to use a first line `shortText`, and remainder in `text`. This commit "fakes" that setup by doing the processing manually.
|
A live preview of this PR will be available at the URL(s) below. https://pr1090-bfd76a6---lit-dev-5ftespv5na-uc.a.run.app/ |
|
Many thanks to #1041 for containing great insights and solutions. This PR fixes the issues in the |
For example see parameters in: /docs/api/ReactiveElement/#ReactiveElement.requestUpdate
| } | ||
| } | ||
|
|
||
| private replaceCommentNodeForLegacyFormat(commentNode: MigrationComment) { |
There was a problem hiding this comment.
This name might also be better as something along the lines of. replaceCommentNodePartsWithMarkdown?
|
I have gone through the docs pages and am much more certain that we haven't lost any documentation and only gained docs from this change. I went through docs with a diff checker. |
Tested by checking `observedAttributes` docs and `updateComplete`
AndrewJakubowicz
force-pushed
the
update-docs-typedoc
branch
from
dd5ea09 to
8247548
Compare
Git is a bit confused about the commits in the change. The only changes not in main are those post the merge commit.
There are certainly improvements that can be made with the newer TypeDoc version. However this PR aims to change the
pages.jsondata as little as possible.To achieve this I've added a glue function which takes the new
TypeDoc.Commentnode and basically replaces it with the legacy fields (shortTextandtext) which is what we expect when generating the HTML for the docs.Because of subtle changes in generation, I've also updated the template to fix the
Parameterstable. For example, compare the preview url with production at:This version of TypeDoc supports TS 5.0.
Testing
I went page by page in the v2 docs and diffed them. The upgraded TypeDoc pages seem to add some additional "View Source" links.
E.g.,
Part of #1074
Screenshots
With this PR:
On prod (notice lack of descriptions in the Parameters):
