search

TypeStrong / typedoc-auto-docs

An idea from TS Discord to automatically render docs for the ecosystem, similar to docs.rs and doc.deno.land
MIT License
10 stars 4 forks source link

Typedoc? #8

Open keithlayne opened 3 years ago

keithlayne commented 3 years ago

It's in the repo name, but based on @Gerrit0 's comments and what we're trying to do, maybe it's not the right tool?

I think certainly it's the starting point, and the point of this project is not to create a TS doc generator.

The main motivating thought here is that typedoc has to do a ton of things that we don't care about:

Whereas we want basically to have consistent, generic docs for all the packages. Possibly a narrower tool serves the purpose better, without the pain.

Or maybe using typedoc as a lib ultimately serves us perfectly, or we contribute what we need upstream.

Bonus points for ripping off Gerrit without attribution 🚎

cspotcode commented 3 years ago

This is a good question and I don't have any good answers.

I have always assumed typedoc is the only tool that correctly uses TS's typechecking APIs to document (inferred) types correctly. That assumption might be wrong; I'm not sure.

Is apiextractor worth looking at? https://api-extractor.com/

Gerrit0 commented 3 years ago

Things I would change if I was designing a tool from the ground up today, rather than maintaining something that's been around for a while:

  1. Tie into what TypeScript does more. TypeScript parses comments, and there's a very nice Symbol.getDocumentationComment method that gives you parsed docs! This is what the VS language server uses, so what it returns will usually be better. TypeDoc doesn't use it because TypeDoc tries to provide good support for namespaces, and comments on namespaces merged with other types behave poorly when you use this method.
  2. Focus on supporting common patterns, not every obscure awful pattern that people can contort TypeScript into doing. Mixins? Sorry, no.
  3. Seriously consider what the point of the documentation is. I believe that a documentation site will never be able to compete with an IDE in being the go to reference for library methods. My usage of MDN dropped by a LOT when I started using VSCode and had go to definition for all the standard functions... I think I've been there like 3 times in the past month, and maybe 1 of those were for a JS function. If the documentation site's goal isn't to compete with quick references - what is it for? One thing it is useful for is getting a feeling for what the API surface of a library you are evaluating looks like. With that goal, do you care about the implementation details of UnionToIntersectionWithBooleanHandling, or do you just care that it exists and takes one type parameter? How much information is useful?

I wonder sometimes why I work on TypeDoc... Personally, I'd rather have a good definition file than TypeDoc generated docs.

cspotcode commented 3 years ago

Interesting, do you think 1. and 2. could be implemented as breaking changes in a fork of typedoc? Could 3. be implemented as a more minimal theme? Could be a fun project, to see how nice we can make typedoc if we embrace breaking changes.

futurGH commented 3 years ago

This is a good question and I don't have any good answers.

I have always assumed typedoc is the only tool that correctly uses TS's typechecking APIs to document (inferred) types correctly. That assumption might be wrong; I'm not sure.

Is apiextractor worth looking at? api-extractor.com

After having toyed with API Extractor for weeks on a similar-ish project on a much smaller scale, my opinion is that, given Gerrit's comments on what a documentation site should do as well as the general direction of this project, your best bet would be to either go lower level with the TS Compiler API itself (or maybe a package like ts-morph to abstract away some of that) or to just use a hodgepodge of what TypeDoc provides.

API Extractor itself is somewhere in the middle, and in my opinion is just not the right tool if you're looking for a generic enough program that can generate documentation from anything that isn't written with the generator itself in mind.

keithlayne commented 3 years ago

Maybe it would be valuable to list what you like/don't like about similar projects, especially rust and deno, since those are mentioned as motivation. I know when I'm stuck doing ruby, where IDE integration is somewhere between hard and impossible, I've found the universal-doc-site-with-all-the-versions to be really useful.

Stuff like layout/presentation is important. I personally find typedoc's default to be hard to navigate, but that's most likely due to lack of using it. If we plan to take rendering upon ourselves, then we can do whatever we want, and the main problem is extracting the info.

One thing I don't know how to do in vscode for example is to look at the actual JS/TS sources of a function I'm looking at. Granted that's not my most common wish, but sometimes it's really important.

Gerrit0 commented 3 years ago

I just remembered https://paka.dev/npm/fp-ts/v/2.10.5/ today, which shares a lot of the same goals as this project, definitely worth looking at and maybe some discussion with @jasonkuhrt.

cspotcode commented 3 years ago

Oh yeah, I think I remember it popping up on Reddit years ago, but I didn't see it since. Where is the code?

jasonkuhrt commented 3 years ago

@cspotcode this is less than a year old so you must be thinking of something else. The tool is private source right now.

keithlayne commented 3 years ago

@jasonkuhrt that looks great. It's looks like that's actually pretty much the thing i want from the thing we've been talking about. I like all the info in one place.

Any place we can look for more info? Is it something that's private-for-now or will probably stay that way? Sorry if I missed something obvious. Thanks for dropping in, BTW.

jasonkuhrt commented 3 years ago

Any place we can look for more info?

You can join our discord for most up to date info if you're curious https://discord.gg/fEGNFsJs.

Is it something that's private-for-now or will probably stay that way?

Uncertain at this point.

that looks great. It's looks like that's actually pretty much the thing i want from the thing we've been talking about. I like all the info in one place.

That's great to hear! More feedback always welcome in Discord.

Thanks for dropping in, BTW.

Thanks @gerrit0 for that!