TypeScript handler

[pawamoy]

Is your feature request related to a problem? Please describe.

Opening for visibility.

Describe the solution you'd like

A TypeScript handler.

Additional context

Could use api-extractor

---

@squidfunk @samuelcolvin could you describe what objects you would like to document in API refs? Do you have examples of API refs for TypeScript libraries that I could draw inspiration from? For example, looking at sp-core-library, I see that we should document classes (+ methods and properties), interfaces (+ methods and properties), type aliases, enumerations (+ fields). Maybe also "modules" and "variables"?

Also, could let me know if API Extractor would fit your workflow/projects? If not, I can write an extractor in Python (I actually already started), but that will take more time.

Also also, it would be great if experienced TypeScript devs could share documents about file layouts and conventions regarding TypeScript packaging and exposing public APIs 🙂

---

Notes to myself

• https://medium.com/@martin_hotell/interface-vs-type-alias-in-typescript-2-7-2a8f1777af4c
• https://stackoverflow.com/questions/51131898/what-is-the-difference-between-type-and-class-in-typescript/51132333#51132333

[squidfunk]

For me, it's packages in a mono repo (example), then in each package all exported functions incl. their signatures, as well as interfaces, types and exported variables. So, taking one of my projects, basically the top-level export:

Maybe also "modules" and "variables"?

Modules are essentially packages, if they have type: module in package.json.

Also, could let me know if API Extractor would fit your workflow/projects? If not, I can write an extractor in Python (I actually already started), but that will take more time.

From their docs:

1. API Report - API Extractor can trace all exports from your project's main entry point and generate a report to be used as the basis for an API review workflow.

Sounds perfect.

2. .d.ts Rollups - Similar to how Webpack can "roll up" all your JavaScript files into a single bundle for distribution, API Extractor can roll up your TypeScript declarations into a single .d.ts file.

Nice feature, don't know if it's necessary for the handler.

4. API Documentation - API Extractor can generate a "doc model" JSON file for each of your projects. This JSON file contains the extracted type signatures and doc comments. The api-documenter companion tool can use these files to generate an API reference website, or you can use them as inputs for a custom documentation pipeline.

Sounds great as well.

[kylebarron]

Also in related prior work for research: Typedoc. It's good, but having something that integrates with mkdocs would be awesome

[kylebarron]

I don't know the internals of mkdocstrings and how handlers work, but I think the --json output flag of typedoc could be really useful for this. I don't know API extractor well, but I'd wager that typedoc might be better for this because it's already focused on documentation.

I have a TypeScript project that has existing typedoc-based documentation (hosted online here). And here attached docs.json is the JSON output from typedoc. (I ran yarn typedoc --json docs.json from the root of the project). typedoc's JSON output is described here with its own output on typedoc's source here.

Maybe this is helpful here?

[pawamoy]

That is super helpful, thanks a lot! I came across Typedoc 3 weeks ago, when someone pointed me to it in this tsdocs issue, but didn't get time to try it yet. It looks exactly like the kind of tool a mkdocstrings handler could use 🙂

[kylebarron]

I'm curious if you have an idea of how big a lift this is to implement? I'd love having both python and TS api docs in a single mkdocs-based website instead of having to switch between mkdocs and typedoc

Is there something I can help with outside of digging into a full handler implementation?

[pawamoy]

@kylebarron Here's my experience:

• If there's a tool that reads this language's sources and outputs JSON (or any other serialized format really), then it's easy: it just needs a bit of fiddling to transpose the serialized data into Python objects, for use in Jinja templates. There's Typedoc for TypeScript (thanks!), I'm working on its integration in a handler in griffe-typedoc and mkdocstrings-typescript (public/empty interfaces for the insiders repos 😉)
• If there's no such tool, then it is still possible to use treesitter to write an AST visitor that builds the required API data from sources. Before I learned about Typedoc, I started working on that too, in griffe-typescript (again, public facing repo). How easy it is then depends on one's knowledge of the language in question. Since I don't know TypeScript, this would have been hard (I would have made wrong choices in data structures for example) or long to get a prototype (needing help from others who know the language better).

If you're willing to help, I can give you collaboration access to the relevant repositories, and we'll chat there in issues, and in return I can give you free access to Insiders. Let me know what you think (feel free to drop me a message on Gitter/Matrix or at pawamoy@pm.me) 🙂

[pawamoy]

@samuelcolvin on what repository of yours could I test the handler?
I'm looking at https://github.com/pydantic/FastUI's sources but can't find any "docstrings".

[samuelcolvin]

It was FastUI, but I haven't got around to writing them yet. Sorry.

[pawamoy]

No worries, just wanted to make sure. Docstrings are not the most difficult part anyway. I'll start testing on FastUI 🙂

[pawamoy]

@samuelcolvin I've published a first prototype. Insiders have gained access to it.

If you want to test it on FastUI:

# Enter your local clone.
cd FastUI

# Prepare a Python virtualenv.
python -m venv .venv
. .venv/bin/activate
python -m pip install mkdocs mkdocs-material mkdocstrings

# If using PyPI Insiders (https://pawamoy.github.io/pypi-insiders/):
pypi-insiders server start
pypi-insiders repos add pawamoy-insiders/griffe-typedoc:griffe-typedoc
pypi-insiders repos add pawamoy-insiders/mkdocstrings-typescript:mkdocstrings-typescript
pypi-insiders repos update
python -m pip install mkdocstrings-typescript

# Else:
python -m pip install git+ssh://git@github.com/pawamoy-insiders/griffe-typedoc
python -m pip install git+ssh://git@github.com/pawamoy-insiders/mkdocstrings-typescript --no-deps

Then apply these changes: pydantic/FastUI@main...pawamoy:FastUI:typedoc (or add a remote pointing to my fork and pull my branch locally), install typedoc with npm, and run python -m mkdocs serve.

[pawamoy]

@squidfunk you can follow a similar approach for your mono repo, my changes are here: squidfunk/mono@spike/typedoc...pawamoy:mono:spike/typedoc.

[pawamoy]

Keep in mind this is a very early prototype, the rendered docs are super raw 😅
If you play with it, don't hesitate to open as many issues as you want at https://github.com/mkdocstrings/typescript (for the rendering part) and/or https://github.com/mkdocstrings/griffe-typedoc (for the data models part). You can open them all in the former, that's fine.

If you want to tweak things locally, install both mkdocstrings-typescript and griffe-typedoc in editable mode, as usual.