gcanti / gcanti/docs-ts

Document how to make use of & debug the example type checking?

Open
#59 2 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.