4 ms·

Show HN: Automatic Documentation for TypeScript Packages

14 points by velut 5y ago

velut 5y ago
Hi HN, After working on a mixed Go/Javascript project and wishing there was something similar to GoDoc for npm packages, I started working on jsDocs.io with the objective of it being the easiest way to generate and view the public API and documentation of npm packages. Currently, jsDocs.io supports packages that contain Typescript source files (.ts) or definition files (.d.ts); you can check out some packages below. The project is open source and available on GitHub at https://github.com/jsdocs-io https://github.com/jsdocs-io I'm happy to answer your questions. https://www.jsdocs.io/package/query-registry https://www.jsdocs.io/package/query-registry https://www.jsdocs.io/package/faastjs https://www.jsdocs.io/package/faastjs https://www.jsdocs.io/package/got https://www.jsdocs.io/package/got
slimsag 5y ago
Very cool velut! I'm super excited to see this type of documentation roll out to more languages, I quite firmly believe this is a great boon to developer productivity in general. I'm glad to see I am not the only one :) I actually believe in this so much that I have been working on a language-agnostic version of this in my spare time on the side as a fun hack-project, and also recently convinced others at my work (Sourcegraph) of how good an idea this is: over there we're building this on top of LSIF (https://lsif.dev https://lsif.dev) by having language indexers emit documentation in a structured form that makes sense for the given language (so the structure of documentation is determined by the language indexer, and the "browser" / "layout" for it could be a website like this, your editor, generating a static Markdown file, etc.) For example, some really quick/hacky Markdown I generated just now from LSIF data for the Go HTTP packages here: https://gist.github.com/slimsag/069d8498890ea6a3ec85dee3ef6f18c8#net-http https://gist.github.com/slimsag/069d8498890ea6a3ec85dee3ef6f... Not trying to advertise anything here, just trying to say THIS IS SO COOL! I hope we get this for more languages! Some others I know of: * Go: https://pkg.go.dev https://pkg.go.dev and https://godocs.io https://godocs.io ("the good one") * Rust: https://docs.rs https://docs.rs * Java: https://javadoc.io https://javadoc.io * Zig: https://ziglang.org/documentation/master/std/#builtin https://ziglang.org/documentation/master/std/#builtin I'd be keen to hear if anybody knows of ones I don't!
- velut 5y ago
  Thank you for your kind words! Your LSIF approach sounds interesting, I'll look into it. Another documentation host I know of is https://hexdocs.pm/ https://hexdocs.pm/ for Elixir packages.
acemarke 5y ago
Interesting. I recently found a similar tool that appears to be in alpha, at https://paka.dev https://paka.dev . I'm actually interested in trying to find a TS API docs generation tool that I could integrate with Docusaurus for use with the Redux libraries docs sites: https://github.com/reduxjs/redux-toolkit/issues/1046 https://github.com/reduxjs/redux-toolkit/issues/1046 I'm curious if you think that JSDocs could be used that way.
- velut 5y ago
  Thank you for your question, I don't have experience with Docusaurus but I'll try to list a few ideas, let me know if it can help you. If you only need raw package metatada (signatures, docs...) that Docusaurus will render somehow at build time you may use my extractor which outputs a plain Javascript object with the collected information (see https://github.com/jsdocs-io/extractor/blob/main/test/package-snapshots/__snapshots__/query-registry.test.ts.snap https://github.com/jsdocs-io/extractor/blob/main/test/packag...). If you need pre-rendered docs that Docusaurus will embed in a page you may implement something like a React component (see https://github.com/jsdocs-io/web/blob/main/src/components/package/PackageDeclarationSection.tsx https://github.com/jsdocs-io/web/blob/main/src/components/pa...) and use the raw metadata as component props. If you need a pre-rendered page that Docusaurus will collect, you may want to look into https://www.npmjs.com/package/@microsoft/api-extractor https://www.npmjs.com/package/@microsoft/api-extractor which can directly output Markdown files (as well as JSON files) but requires some initial setup to get working.
eyelidlessness 5y ago
This is cool. Looks like you’re using Prism for syntax highlighting. Would you consider supporting Shiki (as well)? It uses the same tokenizer and themes as VSCode, and there are cool plugins such as shiki-twoslash which adds support for TypeScript features like type error highlighting and symbol references (and quite a bit more).
- velut 5y ago
  Thank you! Yes, I use prism-react-renderer for syntax highlighting. I did not know about Shiki, but I'll look into it.

14 points by velut 5y ago

Hi HN, After working on a mixed Go/Javascript project and wishing there was something similar to GoDoc for npm packages, I started working on jsDocs.io with the objective of it being the easiest way to generate and view the public API and documentation of npm packages. Currently, jsDocs.io supports packages that contain Typescript source files (.ts) or definition files (.d.ts); you can check out some packages below. The project is open source and available on GitHub at https://github.com/jsdocs-io https://github.com/jsdocs-io I'm happy to answer your questions. https://www.jsdocs.io/package/query-registry https://www.jsdocs.io/package/query-registry https://www.jsdocs.io/package/faastjs https://www.jsdocs.io/package/faastjs https://www.jsdocs.io/package/got https://www.jsdocs.io/package/got

slimsag 5y ago

Very cool velut! I'm super excited to see this type of documentation roll out to more languages, I quite firmly believe this is a great boon to developer productivity in general. I'm glad to see I am not the only one :) I actually believe in this so much that I have been working on a language-agnostic version of this in my spare time on the side as a fun hack-project, and also recently convinced others at my work (Sourcegraph) of how good an idea this is: over there we're building this on top of LSIF (https://lsif.dev https://lsif.dev) by having language indexers emit documentation in a structured form that makes sense for the given language (so the structure of documentation is determined by the language indexer, and the "browser" / "layout" for it could be a website like this, your editor, generating a static Markdown file, etc.) For example, some really quick/hacky Markdown I generated just now from LSIF data for the Go HTTP packages here: https://gist.github.com/slimsag/069d8498890ea6a3ec85dee3ef6f18c8#net-http https://gist.github.com/slimsag/069d8498890ea6a3ec85dee3ef6f... Not trying to advertise anything here, just trying to say THIS IS SO COOL! I hope we get this for more languages! Some others I know of: * Go: https://pkg.go.dev https://pkg.go.dev and https://godocs.io https://godocs.io ("the good one") * Rust: https://docs.rs https://docs.rs * Java: https://javadoc.io https://javadoc.io * Zig: https://ziglang.org/documentation/master/std/#builtin https://ziglang.org/documentation/master/std/#builtin I'd be keen to hear if anybody knows of ones I don't!

velut 5y ago
Thank you for your kind words! Your LSIF approach sounds interesting, I'll look into it. Another documentation host I know of is https://hexdocs.pm/ https://hexdocs.pm/ for Elixir packages.

acemarke 5y ago

Interesting. I recently found a similar tool that appears to be in alpha, at https://paka.dev https://paka.dev . I'm actually interested in trying to find a TS API docs generation tool that I could integrate with Docusaurus for use with the Redux libraries docs sites: https://github.com/reduxjs/redux-toolkit/issues/1046 https://github.com/reduxjs/redux-toolkit/issues/1046 I'm curious if you think that JSDocs could be used that way.

velut 5y ago
Thank you for your question, I don't have experience with Docusaurus but I'll try to list a few ideas, let me know if it can help you. If you only need raw package metatada (signatures, docs...) that Docusaurus will render somehow at build time you may use my extractor which outputs a plain Javascript object with the collected information (see https://github.com/jsdocs-io/extractor/blob/main/test/package-snapshots/__snapshots__/query-registry.test.ts.snap https://github.com/jsdocs-io/extractor/blob/main/test/packag...). If you need pre-rendered docs that Docusaurus will embed in a page you may implement something like a React component (see https://github.com/jsdocs-io/web/blob/main/src/components/package/PackageDeclarationSection.tsx https://github.com/jsdocs-io/web/blob/main/src/components/pa...) and use the raw metadata as component props. If you need a pre-rendered page that Docusaurus will collect, you may want to look into https://www.npmjs.com/package/@microsoft/api-extractor https://www.npmjs.com/package/@microsoft/api-extractor which can directly output Markdown files (as well as JSON files) but requires some initial setup to get working.

eyelidlessness 5y ago

This is cool. Looks like you’re using Prism for syntax highlighting. Would you consider supporting Shiki (as well)? It uses the same tokenizer and themes as VSCode, and there are cool plugins such as shiki-twoslash which adds support for TypeScript features like type error highlighting and symbol references (and quite a bit more).

velut 5y ago
Thank you! Yes, I use prism-react-renderer for syntax highlighting. I did not know about Shiki, but I'll look into it.