Document how to make use of & debug the example type checking?
- Dominant language
- TypeScript
- Stars
- 105
- Forks
- 18
- PR merge metrics
- No merged PRs in 30d
Description
**Do you want to request a _feature_ or report a _bug_?**
_feature_
**What is the current behavior?**
I have a [library I am trying to document](https://github.com/Docmaps-Project/docmaps/pull/34) using docs-ts, because it is a library of io-ts codecs. I have written examples for each of the core codecs and suddenly encounter an issue where `npx docs-ts` fails like that:
```
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /Users/eve/docmaps/packages/ts-sdk/docs/examples/index.ts
at new NodeError (node:internal/errors:399:5)
at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:79:11)
at defaultGetFormat (node:internal/modules/esm/get_format:121:38)
[ ... omitted ... ]
code: 'ERR_UNKNOWN_FILE_EXTENSION'
}
```
It seems like docs-ts is doing some awesome footwork to prove that my examples actually compile or type check anyway. However I haven't found docs or other issues that reference this behavior. Could we get an explainer on this, or info in the docs? I need to write examples, auto checking is optional feature for me so I would also be happy turning it off if there is need.
Thanks very much!
**Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?**
NodeJS 18.14.0, macos 13.3, docs-ts 0.7.2
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reproducing `npx docs-ts` with the reported `docs/examples/index.ts` example and inspect how the command checks TypeScript examples. Document why this type-checking step produces the `.ts` extension error, how to debug it, and whether it can be disabled; the work is done when these steps are clear to users.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100