Version 0.20 tracking #1364
Comments
|
@Gerrit0 I'm happy to help with light/dark theme for typedoc, based on css custom properties and prefers-color-scheme. Maybe using this: https://github.com/GoogleChromeLabs/dark-mode-toggle |
|
Thanks @bennypowers! We've chatted about this a bit on Discord. What's been done this week is published as Maintenance
Development
Work added
|
|
Fairly small update this week, I didn't have much time to work on TypeDoc. Maintenance
Development
|
Typedoc is jsdoc for typescript. Unfortunately, it doesn't yet to anything very useful because we need library mode, which is currently in development (TypeStrong/typedoc#1364). But jsdoc doesn't do anything at all so this is better.
|
My apologies for a lack of an update last week - I went out with some friends and didn't handle the junk food well... This week was also fairly unproductive... but at least I did one thing! Work has been very busy, not much brain left over for the weekend. Particularly for the rather tricky task of making comment parsing better. While working on Development
|
|
This weekend I spent trying to avoid the rewrite. I haven't succeeded yet, but I made some good strides, I believe it is possible to (mostly) use the existing architecture and avoid spending a bunch of time rebuilding code that works today. Toward that end, I ripped out a few options:
I mostly have library mode working, but am still dealing with some issues where we sometimes need to create references, and sometimes not.... I suspect I'll have a working prototype next week. |
|
in our typescript library repo, we are experimenting with typedoc to generate api documentation. note : i'm not sure whether it's a bug or not. my current ts config |
|
I wasn't quite able to get library mode working this weekend - mostly due to needing to fix how TypeDoc handles type references. It used to use the
I fixed these issues + restructured the type converters slightly, which makes it possible now to get warnings when TypeDoc doesn't properly implement a converter for some type and also improved the converter speed, lookup is now O(1) instead of O(n) with n being the number of converters. This revealed a few types that we don't handle right now that I didn't have time to get to. I'll probably skip them for now and just focus on getting something working next week.
Plan for next week:
With those done, I'll hopefully be able to put out a beta which works. |
|
The beta is up! I also spent some time this weekend trying to test this on some projects that I know are currently using the library mode build in #1184... for the most part, this seems to work equally as well, though I'm sure that people more familiar with the projects will be able to point out things I've missed. A few notes about usage change:
How library mode works:
This two pass system makes the results more reasonable if you have more than one entry point. Plan for next week:
|
|
This week:
Bonus: Had some extra time:
Plan for next week:
Stretch for next week:
|
|
If you're looking into inheritance, can I encourage you to spend some time on patterns like export function CustomElementMixin<Base extends Constructor<HTMLElement>>(superclass: Base) {
return class Mixed extends superclass {
thing: number;
}
}Expected: I'd expect to see Actual: Typescript ends up copying in the entire HTMLElement interface to the .d.ts, and as a result, typedoc ends up reporting on So yeah this is probably a TS thing, but if you can hack together a nice fix, it would be nice not to have to https://github.com/apollo-elements/apollo-elements/blob/55e943d3eca62541a52881ab4a43ae7bf587a6d1/scripts/fix-typedoc.ts#L174-L189 (turns out JSDOM's So no pressure, but if in the course of things you hack out a fix, I'd be glad to hear it |
|
So... mixins != inheritence, not even close. Mixins = hack everything together in a construct which breaks all reasonable ways of interacting with the compiler API. I tossed that into a file and ran the current beta on it, and apparently I've already made the output worse.
I think mixins need their own special converter + reflection type. Useful docs for them aren't anywhere near the same as useful function docs.... I'll make a note in my list to look at that, but can't promise I'll get to it before releasing 0.20. |
|
No pressure. Thanks for the update. |
|
(I pulled the above questions into new issues) I've been busy. I took some of this week past off, so had extra time for TypeDoc.
|
|
@Gerrit0 0.20.0-beta.24 looks awesome, seems like i can finally point typedoc to the src folder instead of type declarations (src is commonjs with JSdoc types) One thing that looks broken is the export symbol name:
|
|
That export name is correct - 0.20 documents what is exported under those names. TypeScript's equivalent of However, because your index.is file does the more TS friendly You probably don't want to pass TypeDoc the src directory. If you instead give it src/index.js you should have much better output. |
export = Key;
import { Key } from "./key";typedoc can't get Anyhow changed everything to named exports and stuff starts to look nice and pretty, but still have errors in my utils file
<ref *2> [
<ref *1> NodeObject {
pos: 208,
end: 248,
flags: 4325376,
modifierFlagsCache: 536875008,
transformFlags: 0,
parent: NodeObject {
pos: 186,
end: 252,
flags: 4325376,
modifierFlagsCache: 0,
transformFlags: 0,
parent: [NodeObject],
kind: 311,
comment: undefined,
tags: [Array]
},
kind: 331,
tagName: IdentifierObject {
pos: 209,
end: 216,
flags: 4325376,
modifierFlagsCache: 0,
transformFlags: 0,
parent: [Circular *1],
kind: 78,
originalKeywordKind: undefined,
escapedText: 'typedef'
},
comment: undefined,
typeExpression: NodeObject {
pos: 217,
end: 233,
flags: 4325376,
modifierFlagsCache: 0,
transformFlags: 0,
parent: [Circular *1],
kind: 301,
type: [NodeObject]
},
fullName: IdentifierObject {
pos: 234,
end: 248,
flags: 4325376,
modifierFlagsCache: 0,
transformFlags: 0,
parent: [Circular *1],
kind: 78,
originalKeywordKind: undefined,
escapedText: 'PromiseOrValue'
},
name: IdentifierObject {
pos: 234,
end: 248,
flags: 4325376,
modifierFlagsCache: 0,
transformFlags: 0,
parent: [Circular *1],
kind: 78,
originalKeywordKind: undefined,
escapedText: 'PromiseOrValue'
},
locals: Map(1) { 'T' => [SymbolObject] },
symbol: SymbolObject {
flags: 524288,
escapedName: 'PromiseOrValue',
declarations: [Circular *2],
parent: [SymbolObject],
isReferenced: 67108863,
id: 354
},
localSymbol: SymbolObject {
flags: 0,
escapedName: 'PromiseOrValue',
declarations: [Array],
parent: undefined,
exportSymbol: [SymbolObject]
},
id: 3317
}
]if i skip the |
While typedoc could figure out that your local variable is named Can you open a new issue for the issues you're seeing with instructions for reproducing them? I'd like to keep this issue fairly clean for people looking for updates on the 0.20 release. |
|
Since the last update v0.20.0-beta.26 is out with:
I also spent a fair bit of time attempting to solve the generic issue from #\2 above, but wasn't able to fully solve it this week. |
|
thanks for the new release, I just played around with it. Looks great so far, one issue I stumpled upon: this somehow let typedoc think it needs to pick up the name and README from the root, instead of the current directory. The types are documented correctly though, only the "Project" name and the content of the readme file is wrong. Thanks for your work! Update 1: Interesting, in another project it acts differntly. the package name is applied correctly, but the package itself do not have a README, but a folder on level up has one, and this one is picked. The difference between the two monorepos is, that I hoist node modules in the one (where it's not working), and not in the other. It's the only difference I could find, the strange thing is.. typescript and typedoc are both installed in the "root" of the monorepo. |
|
Hmm... that looks like an unintentional side effect of how the PackagePlugin grabs paths changing to deal with multiple projects - it used to get the root names from the singular program, but I'm guessing that what TypeScript considers "root names" due to a change in how the program is constructed, so it is including declaration files in node_modules among the root names - which would explain why hoisting makes a difference. Looking at this again, it doesn't make much sense to me to use the root names here - it's more appropriate to look for a readme beginning with the common directory for the entry points. This, as well as a fix to improve the speed for repos using project references, but not a solution style tsconfig, has now been published in 0.20.0-beta.27 (or will shortly... CI is running) |
It looks like typedoc 0.20 beta may now support the library mode that was keeping us on 0.17.0-3: see TypeStrong/typedoc#1184 (comment). See also TypeStrong/typedoc#1364
|
The tag |
|
I tried the |
|
I've just tried NodeJS - any version, OS - Windows 10. My {
"name": "SUB-EVENTS v1.8",
"readme": "README.md",
"mode": "file",
"out": "docs",
"theme": "minimal",
"excludeExternals": true,
"excludePrivate": true,
"excludeNotExported": true,
"disableOutputCheck": true,
"exclude": [
"./extras/**/*.ts",
"./test/**/*.ts"
]
} |
|
@vitaly-t remove the „mode“ option. It’s was removed as „library“ mode is now the default. |
|
@Supereg Ok, just did it, so the first error is gone, but the second one remains: Is there some other default setting I need to apply for this option? Note that if I just remove that option from configuration, I start getting this: |
|
@vitaly-t
You will need to set the entry point for your application e.g. your index.ts or whatever. entry point should be documented in the typedoc docs. |
Fixed in beta 28, no idea what I was thinking there... For some reason I changed the code so that
Beta 28 is out - I think I finally worked out all the edge cases with inheriting from generic classes. There's not much left on the todo list now - https://github.com/TypeStrong/typedoc/projects/5 |
|
+3 betas.. up to 31 now. 29 - Fixed missing comment detection on some variable-functions #1421. I am aiming for the 28th for a full release. The one remaining bug I have to resolve is missing index signatures, after that the remaining tasks are mostly updating documentation. I did pull one feature out of this release - respecting the OS theme in the default themes. This might still end up getting released this year, but I decided I wanted to fix some other issues with the themes while I'm at it, so am putting it off a bit longer. |
|
0.20 is out! https://github.com/TypeStrong/typedoc/releases/tag/v0.20.0 Please open a new issue if you discover any issues with it :) |
|
@Gerrit0 Finally getting this integrated into my project. Works like a dream. I don't see one of those "buy me a coffee/beer" buttons anywhere but just want to say you deserve it 🍻 Thanks for all your work on this. |
This issue tracks the work being done on the next feature release of TypeDoc. I will be posting a weekly update here covering what I've done this week, as well as what's next to be done.
You can try out a beta of 0.20 by installing
typedoc@betawithnpm i typedoc@beta.Originally, this release was slated to be version 1.0, it contained a major rewrite which fixed most to all of the issues I have with the current implementation of TypeDoc. However, I've since realized that this was a bad idea - I broke too many things, so "library mode" will be releasing as 0.20 before the end of the year.
Old text
This issue tracks the work being done on version 1.0. I will be posting a weekly update here covering what I've done this week, any new problems discovered, and updating the checklist in this post with what's been completed. The checklist in this post was originally taken from this post in the original PR, without including any of the already completed items.
If you are interested in looking at the work in progress package, you can install
typedoc@dev, which will be published whenever a change in version is pushed to thelibrary-modebranch.At the current rate that I'm getting things done, it's looking like this won't be ready until November/December... I was really hoping for sooner, but can't devote every weekend to this, though I try to do at least one task per week ;)
Tasks
TypeDoc proper
ObjectReflectionconverter (medium)@function, Variables of kindConditionalExpressionhave defaultValue set to condition #401, )Comments
@categorywork again (medium)@inheritdocwork (small/medium)Themes
application.options)Plugins / Developer Docs
Extra (nice to have, but won't block a release)
@eventought to work. The old way of handling it flat won't work anymore... and it isn't particularly clear how it should be used.Future (almost certainly not in 1.0, but I'm thinking about it)
///comments Triple-slash comments for JSDoc microsoft/TypeScript#39930Help out
There's still quite a bit to be done. Help on any of the uncompleted items above is greatly appreciated. I could especially use some help on making the default theme better - frontend dev is not my specialty. If you are having trouble, feel free to reach out by making an issue for the task you're working on, through the TypeScript Discord, or through the TypeDoc Gitter.
The text was updated successfully, but these errors were encountered: