Update TypeDoc to latest - 0.24.6 #1093
Conversation
|
A live preview of this PR will be available at the URL(s) below. https://pr1093-b007374---lit-dev-5ftespv5na-uc.a.run.app/ |
|
Manually tested and diff checked generated pages on the most recent preview URL and as far as I can find - we have no content changes. External links (E.g., to MDN from native types work), and internal links, (e.g., |
AndrewJakubowicz
requested review from
augustjk and
justinfagnani
and removed request for
justinfagnani and
augustjk
This fixes cross linking in type signatures etc. The bug was that reflected types now have a `target` property that links to the `id` of the original declaration.
AndrewJakubowicz
force-pushed
the
update-docs-typedoc-2
branch
from
15047da
to
c6f2a80
Compare
|
Thanks for the review - did a rebase with main. Will merge after reviewing new preview url. |
| // The "target" key is unstable causing our "Check API data is in | ||
| // sync" approach to fail. We also do not use this key. | ||
| key === 'target' | ||
| key === 'target' || |
There was a problem hiding this comment.
We're now using the key of 'target' for referencing reflected node as per the PR description, and usage in line 425. Do we now want to keep this around?
There was a problem hiding this comment.
Correct that we use target and id for tracking declarations and references to declarations. This just filters out keys that we don't need for pages.json -> the rendered html. So we can remove target from the cached output.
Edit: We use id and target to manipulate other data fields. E.g., location. But then they are not required as an artifact.
| @@ -28,14 +28,14 @@ export interface MigrationComment | |||
|
|
|||
| export interface ExtendedDeclarationReflection extends DeclarationReflection { | |||
| location?: Location; | |||
| externalLocation?: ExternalLocation; | |||
There was a problem hiding this comment.
Do we need to add externalUrl here instead? Maybe not since we're just doing an inline assertion to add anyway, but also maybe yes for documentation purposes.
There was a problem hiding this comment.
externalUrl is already documented natively on DeclarationReflection. E.g., it's a TypeDoc type that I am "correcting". However I can add it here for additional documentation.
There was a problem hiding this comment.
Oh if it's already there the no problem! I was just going based off the diff.
|
Haha! This is gonna be the last update for a while of this size. :P Thank you for the review. |
|
🙏 Thank you so much! |
This bumps TypeDoc to the latest version. Only one minor patch from the last PR: #1090
My hope is that this gives us some more tools for the labs documentation. For example a new
project root pathoption is now required & may fix the strange file paths seen in #1092.Regardless - while I have some context in this area - I'm trying to get us as updated as possible.
Changes
kindString. We use this extensively in ourapi.htmltemplate so I needed to add it back using a full tree traversal.targetto reference the id of the declaration for reflected nodes. This initially broke all linking between symbols. Fixed once I figured out the id was ontarget.Testing
Very manual process again.
This was tested by once again going page by page in the docs and diff checking the content.
I also checked the View Source links continued to work & generated pages look the same between prod and this PR.
Issues found and fixed list
These issues occurred because initially I did not fully traverse the TypeDoc tree to add
kindStringfields back. Issue resolved by a full traversal.enableWarninglost its type: https://pr1093-b007374---lit-dev-5ftespv5na-uc.a.run.app/docs/api/LitElement/#LitElement.enableWarningcreationScopebecame a TODO type: https://pr1093-b007374---lit-dev-5ftespv5na-uc.a.run.app/docs/api/LitElement/#RenderOptions.creationScope