gabrielcsapo / gabrielcsapo/docusaurus-plugin-api-extractor

Documentation for `options.entryPoints` / monorepo

Open
#34 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
6
Forks
3
PR merge metrics
No merged PRs in 30d

Description

@gabrielcsapo thank you for the package. I will try typedoc for now but would like to leave feedback on what I've tried

> node v19.0.0
> docusaurus-plugin-api-extractor": "^2.0.4"
> "typescript": "^4.7.4"
> "@microsoft/api-extractor": "^7.33.5",

This looks like it'd be very valuable ([link](https://github.com/gabrielcsapo/docusaurus-plugin-api-extractor/tree/33ae7f6/plugin/docusaurus-plugin-api-extractor)):

> `options.entryPoints`
> If you have multiple packages that you would like to generate you can use `entryPoints`. The plugin will generate temporary a [api-extractor.json](https://api-extractor.com/pages/configs/api-extractor_json) file for each entry and use that information to setup [mainEntryPointFilePath](https://api-extractor.com/pages/configs/api-extractor_json/#mainentrypointfilepath) and other path related options.
>
> ```typescript
> module.exports = {
> plugins: ['docusaurus-plugin-api-extractor', {
> entryPoints: {
> api: './dist/api/index.d.ts',
> client: './dist/client/index.d.ts',
> library: './node_modules/my-library/index.d.ts'
> }
> }],
> };
> ```

It says the following:

> The plugin will generate temporary a [api-extractor.json](https://api-extractor.com/pages/configs/api-extractor_json) file for each entry

Therefore, I assume there's no necessicity to manually create an `api-extractor.json` file.

However if you follow the instructions, it simultaneously requests an `api-extractor.json` that can't possibly be generated yet AFAIK

```console
yarn docusaurus api-extractor:run --verbose --ci
yarn run v1.19.0
$ docusaurus api-extractor:run --verbose --ci
[ERROR] Error: ENOENT: no such file or directory, open 'api-extractor.json'
[INFO] Docusaurus version: 2.2.0
Node version: v19.0.0
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
```

There aren't any examples of a monorepo + docusaurus site, which would be valuable in demo'ing this feature if it's operational

So far I've found no way to actually use the official [api-extractor](https://github.com/microsoft/rushstack/tree/main/apps/api-extractor) package - it seems sparsely documented outside of Microsoft's internal projects at the moment.

Contributor guide

Open the contributing guide

Research direction

Start with the documented options.entryPoints behavior and the api-extractor.json configuration referenced in the issue, then reproduce the yarn docusaurus api-extractor:run --verbose --ci command. Add a monorepo and Docusaurus example, and clarify whether users must create api-extractor.json manually and how the command should complete.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.