[WIP] Upgrade to TS 3.0 #5030
[WIP] Upgrade to TS 3.0 #5030
Conversation
|
Ahh this is awesome. Thanks @blink1073! |
|
Awesome, thanks! I'm thinking we should maybe abandon Typedoc. It seems the project has stalled, and it is preventing us from using newer Typescript syntax (there are a few places noted in the code that we'd like to use new syntax). One question is: how much are the api docs being used? Perhaps we should add a google analytics tracker to give us an idea. (plus it might be interesting to see which api pages are most used...) |
|
This was way easier than I thought. I thought we would be adding a references section to each package, keeping it in sync with the dependencies for the packages. We might eventually do that, but for now this makes the transition nice and smooth. |
|
@jasongrout if by typedoc you mean the following: https://jupyterlab.github.io/jupyterlab/globals.html I can let you know that personally I initially found it quite confusing, and in the end I found following definitions within visual studio code and reading source code to be easier. |
Yes, that's what I mean. Thanks for your feedback! |
|
@SimonBiggs, was it confusing because of the way it was structured? If we had a better way to get at a class definition page, would that help? |
|
I guess traversal through the code base by using control + click within Being able to navigate that way, directly as I am writing code, is hard to When I was new to the code base, typedoc was the only online documentation at Personally I found, to understand what was really going on initially, I |
|
I myself have never used the TypeDoc output for anything, preferring to read on Github or in Sublime Text as well. It has been a royal pain to maintain... |
|
Oh no! I thought that I get that even when I add |
|
Oh wait, I made a mistake in specifying the |
|
Okay, this will work, but we do need to do what you thought @jasongrout, maintain the appropriate |
|
yay for incremental compilation! I suppose |
|
It sounds that way, I won't know for sure until build works. |
|
Drat, we need to wait on this problem in watch mode. Otherwise, it works great! |
|
It takes ~1s to build on my machine when there are no changes, and ~73s from scratch. |
|
But the amazing thing is that you can run |
|
Yay, this is wonderful! thanks so much for working on this. I am in favor of removing typedoc. I have never used it while getting acquainted with the codebase and like @SimonBiggs found it much easier to hop around it using vscode. |
|
Am I understanding things right that tsconfig.json references should match package.json references to other jupyterlab packages? I know that typescript has an issue for making it easier to have the references be inferred from other files, but in the meantime is there any checking to make sure those stay in sync? |
examples/console/src/tsconfig.json
Outdated
| "compilerOptions": { | ||
| "outDir": "../build" | ||
| }, | ||
| "include": ["*"], |
There was a problem hiding this comment.
Can these "include": ["*"], options be moved to tsconfigbase?
There was a problem hiding this comment.
Nope, I tried and the files don't get built.
There was a problem hiding this comment.
All paths are relative to the tsconfig file they are in. So anything giving a path has to be in the individual tsconfig files.
Source: I also tried when making the tsconfigbase, and I also read the docs :)
|
The references are populated in our ensure-package script that is run in the integrity script. |
|
Here are all the times we reference a class definition in our docs: My vote is to keep TypeDoc for now. There is an open (passing) PR to upgrade to 3.0: https://github.com/TypeStrong/typedoc/pull/825/files. |
That was fast. There have been open PRs updating typedoc to other TS versions in the past months that went nowhere, though, so I'm not exactly holding my breath. |
|
I'm not one to sit on my hands 😉. TypeStrong/typedoc#826 (comment) |
|
Are we still going to try to get this in for 0.34? |
|
We're blocked on fix in TypeScript. I'll leave this marked as 0.34 in case the fix is available in time. |
|
Update: the fix to TypeScript is done in master and will be backported to 3.0.2. |
|
For reference, the TS issue was microsoft/TypeScript#26147, and the PRs fixing it are linked in that issue. |
|
Update: we are no longer blocked! I'll return to this after #5251. |
|
@jasongrout, why was |
|
If I use |
|
Okay, this is all done pending microsoft/TypeScript#26955. |
|
Rock: meet hard place: TypeStrong/ts-loader#815. I'll remove |
blink1073
force-pushed
the
ts-3.0
branch
3 times, most recently
from
6ddaa68
to
7c474cc
Compare
wip convert to typescript 3.0 Add references field wip ts 3.0 wip ts 3.0 wip ts 3.0 wip ts 3.0 wip ts 3.0 remove debug print update to ts 3.0.3 Update to ts 3.0.3 Use webpack-env types properly Clean up watch mode for metapackage Use typescript@next for now WIP update api docs building WIP update api docs building Fix handling of version in update-dependency lint wip cleanup Remove references from examples Clean up test watch:src scripts Build all the docs Add tdoptions files add missing files cleanup formatting Switch to ts 3.0.3 for now Handle documentation index Do not use references in examples formatting Update tests lint Add a header Remove build compile from tests lint Fix composite lint lint updates lint updates prettier? prettier? Now prettier No integrity Try integrity again Add prettier-changed files cleanup Clean up sibling scripts fix webpack config Fix docs runner cleaup Update handling of integrity Cleanup fix build utils Fix integrity and theme building Only add references if a src folder exists Fix handling of targets check Fix testutils formatting fix docs building Add missing types Add node types for tdoptions as well clean up vega config Fix typings
I'm not sure if it was needed, though I found it a nice confirmation - if I switch to the watch window, I can confirm that the file I was working on was explicitly built. If it's messing up things, feel free to take it back off. |
|
There's an open issue to add support for the rest of the flags for |
lock
bot
added
the
status:resolved-locked
Takes advantage of the new project references feature to simplify how we build our packages.
Everything Just Works ™️ in that each folder gets its own
lib/as if it were built directly, huzzah! However, because the output of metapackage itself has changed, we need to update the way we build our API docs. We need to build docs in each folder and make our own index page. No code has to change, and Typedoc uses its own TypeScript compiler version, so we're good to go. This will actually be an improvement since our current API landing page is awkward.referenceswatchmode in light of these simplificationsupdate:dependency foo@nextwatchscripts - do not use-bin examples since they should be standaloneUpdated status: still blocked on a TypeScript Issue: microsoft/TypeScript#26955