docs: Check TS in docs using typescript-docs-verifier

[maschad]

Closes #1228

[achingbrain]

This is great, really helpful.

I think this should be added to aegir as a doc-check command though, similar to dep-check.

It can manage the tsconfig.json file for the docs then, in the same way we do it for linting.

It also doesn't currently check any code blocks in the docs here, because they are fenced with js as a type and not typescript - ts doesn't seem to work either, though maybe there's some config for that?

[maschad]

Thanks for the feedback.

I think this should be added to aegir as a doc-check command though, similar to dep-check.

Good point, I'll add it as a feature

It can manage the tsconfig.json file for the docs then, in the same way we do it for linting.

A user may want to use a different tsconfig.json in situations like this for instance, so it may be best to specify that separately.

It also doesn't currently check any code blocks in the docs here, because they are fenced with js as a type and not typescript - ts doesn't seem to work either, though maybe there's some config for that?

I think it's because of you were traversing the wrong directory in the script here it works otherwise.

I opened a ticket on aegir once this is closed we can update and review this.

[maschad]

Once ipfs/aegir#1134 is merged and released then this can be reviewed

[achingbrain]

Please can you revert all the formatting changes and stick to the same coding standards as the main codebase. Single quotes for strings, no semi colons, no extra comma for the final entry in a list, etc.

[achingbrain]

The interop suite has a peer dep on aegir@37.x so the dependency tree can't be resolved:

npm ERR! Could not resolve dependency:
npm ERR! peer aegir@"^37.2.0" from @libp2p/interop@4.0.2
npm ERR! node_modules/@libp2p/interop
npm ERR!   dev @libp2p/interop@"^4.0.0" from the root project

This is blocked until libp2p/interop#82 is merged.

[achingbrain]

TBH we may wish to do the aegir upgrade first in it's own PR, then revisit this one once it's merged as adding return types to all the functions will be quite noisy.

[maschad]

Once ipfs/aegir#1255 is merged then we can update to the newest aegir and then land this.

I've upgraded to the 39.0.9

[p-shahi]

this add deps on prom-metrics in the libp2p repo, will wait for the monorepo work to get in follow up in #824
have package.json in docs folder to keep it out of libp2p deps

[p-shahi]

this add deps on prom-metrics in the libp2p repo, will wait for the monorepo work to get in follow up in #824 have package.json in docs folder to keep it out of libp2p deps

Unblocked, @maschad adding to this PR itself

[achingbrain]

The /doc folder should be added to the workspaces list in the root package.json.

It should have a package.json added that contains:

1. The doc-check command
2. The deps needed by the doc examples
3. The dep-check command to ensure the deps don't get out of date (assuming we can make it run on markdown, might need to be a follow up)

[achingbrain]

These comments should follow the same linting rules as the main codebase; comma-dangle is disallowed.

Suggested change

	],
	},
	]
	}

[maschad]

So the doc-check command which utilizes https://github.com/bbc/typescript-docs-verifier only checks that Typescript code snippets compile, it's not a linter. That could be added in a follow up PR but wasn't the original intention of this.

[maschad]

I've added the doc-check command to the docs/ workspace. We will need a follow up PR for:

• doing a dep-check than checks the TS snippets in markdown
• Enforcing linting rules on TS snippets in markdown.

Both of these will be features to be added in https://github.com/ipfs/aegir

[achingbrain]

LGTM, just needs the private flag added to the docs package.json so it doesn't get published.