[gatsby-transformer-documentationjs] - Conflicts With Gatsby Even On Default Gatsby Starter

[Skillz4Killz]

Description

Steps to reproduce

1. gatsby new docs
2. cd docs
3. npm i gatsby-transformer-documentationjs
4. Add to gatsby-config.js

5. Copy the exact query from the plugins readme and add to gatsby-node.js
   

6. gatsby develop

Expected result

The website should load the default starter and console.log() everything the plugin finds.

Actual result

Errors and the gatsby develop cancels.

Environment

  System:
    OS: macOS 10.14.4
    CPU: (4) x64 Intel(R) Core(TM) i5-6500 CPU @ 3.20GHz
    Shell: 3.2.57 - /bin/bash
  Binaries:
    Node: 12.13.0 - /usr/local/bin/node
    Yarn: 1.9.4 - /usr/local/bin/yarn
    npm: 6.12.0 - /usr/local/bin/npm
  Languages:
    Python: 2.7.10 - /usr/bin/python
  Browsers:
    Chrome: 78.0.3904.87
    Safari: 12.1
  npmPackages:
    gatsby: ^2.17.6 => 2.17.6 
    gatsby-image: ^2.2.30 => 2.2.30 
    gatsby-plugin-manifest: ^2.2.25 => 2.2.25 
    gatsby-plugin-offline: ^3.0.17 => 3.0.17 
    gatsby-plugin-react-helmet: ^3.1.13 => 3.1.13 
    gatsby-plugin-sharp: ^2.2.34 => 2.2.34 
    gatsby-source-filesystem: ^2.1.35 => 2.1.35 
    gatsby-transformer-documentationjs: ^4.1.16 => 4.1.16 
    gatsby-transformer-sharp: ^2.3.1 => 2.3.1 
  npmGlobalPackages:
    gatsby-cli: 2.8.5

[LekoArts]

Hi!

Sorry to hear you're running into an issue. To help us best begin debugging the underlying cause, it is incredibly helpful if you're able to create a minimal reproduction. This is a simplified example of the issue that makes it clear and obvious what the issue is and how we can begin to debug it.

If you're up for it, we'd very much appreciate if you could provide a minimal reproduction and we'll be able to take another look. Your current description shows the steps but you're requiring data outside of the starter and hence it's not an appropriate reproduction instruction (because we don't have that data).

Thanks for using Gatsby! 💜

[Skillz4Killz]

Hi @LekoArts

I wasn't sure how to make a minimal reproduction because it required doing the steps inside an existing lib with JSDocs. My goal was to create some nice documentation for a small library. The repo below is a very small library only a couple of files. There is folder called gatsby-docs where I was attempting to get this to work.

Repo: https://github.com/Skillz4Killz/yuuko

1. git clone https://github.com/Skillz4Killz/yuuko.git
2. cd Yuuko/gatsby-docs
3. npm i to install the gatsby node modules
4. gatsby develop

Nothing fancy has been done in the repo besides the reproduction steps I posted above in the original post.

[vladar]

I narrowed it down to the following TypeScript example that fails:

/** Iface Foo */
interface Foo {
    /** field foo */
    foo: string;
}

/** Iface Bar */
interface Bar {
    (
        /** argument bar */
        bar: Foo,
    ): void
}

This also produces a weird document when running documentationjs manually on it (via their CLI): see the gist.

Looks like documentationjs creates multiple tokens for the Foo type (CommandContext in your repo) which transforms to multiple identical nodes in Gatsby. It means that if this is resolved upstream then it should also work in Gatsby.

I guess steps to address this issue are:

1. Try building your docs with regular documentationjs CLI (i.e. run npx documentation build ../src/** -f md --shallow > docs.md from your reproduction repo)
2. If there are issues - resolve them in the documentationjs repo
3. When documentationjs produces expected output - send a note here for the follow-up

Does it make sense for you?

[github-actions]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜