feat: add multi-instance support

[elias-pap]

closes #255

[ghost]

CodeSee Review Map:

Review in an interactive map

View more CodeSee Maps

Legend

[edno]

Thank you @elias-pap for this new feature!!! That's awesome.

I will deep dive into the code asap.

In the meanwhile, could you add some tests that cover the multi instance case?

[elias-pap]

Thank you @elias-pap for this new feature!!! That's awesome.

I will deep dive into the code asap.

In the meanwhile, could you add some tests that cover the multi instance case?

Thanks for this useful plugin @edno !
I added a basic test, let me know what you think.

[edno]

I finished the 1st review.

A few comments, but nothing that requires major changes.

Great job @elias-pap 💪

[edno]

I am wondering if this feature should be closer to the current Docusaurus multi-instance approach, see https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/index.ts#L71

This would mean one command per instance (id), instead of one command for all. That would give a more granular control over the generation to users, and users can still merge both command into a single one with a script.

[elias-pap]

I am wondering if this feature should be closer to the current Docusaurus multi-instance approach, see https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/index.ts#L71

This would mean one command per instance (id), instead of one command for all. That would give a more granular control over the generation to users, and users can still merge both command into a single one with a script.

That's right, this is how I had implemented it initially and the change required is far more simpler:

const command = opts.id === "default" ? "graphql-to-doc" : `graphql-to-doc:${opts.id}`;
.
.
.
return {
    name: "docusaurus-graphql-doc-generator",

    extendCli(cli) {
      cli
        .command("graphql-to-doc")  // replace with .command(command) here
        .option("-s, --schema <schema>", "Schema location")

"default" is the value of DEFAULT_PLUGIN_ID.

I changed my mind later on because this mutates the name of the command, and this seemed a bit weird. Docusaurus handles that detail internally for their docs plugin, so the user does not have to deal with many commands.

But yeah, we can do this instead ! Whatever you think is best.

[edno]

I changed my mind later on because this mutates the name of the command, and this seemed a bit weird. Docusaurus handles that detail internally for their docs plugin, so the user does not have to deal with many commands.

Docusaurus also changes the command name (and description): https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/index.ts#L89

Both approaches are valid. I would like to stay as close as possible to Docusausus behaviour for the v1 (the v2 will one day allow breaking the dependency to Docusaurus).

Ideally, I'd love to see the default command running all. But that will be a nightmare to solve this. And, to stick to KISS principle (I should add this to the contrib guidelines), I think we should go with Docusaurus command per id.

const isDefaultId = opts.id === "default";

const command = isDefaultId ? "graphql-to-doc" : `graphql-to-doc:${opts.id}`;
const description = `Generate GraphQL Schema Documentation for ${opts.schema}`; // trick for helping users

return {
    name: "docusaurus-graphql-doc-generator",

    extendCli(cli) {
      cli
        .command(command)
        .description(description)   

And, we can keep the config.js logic for merging config with cli option. I like that approach, it makes the code cleaner.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[edno]

Released: https://github.com/edno/graphql-markdown/releases/tag/1.9.0 🎉