Gatsby: document helper functions passed to gatsby-node APIs

[chmac]

Description

I have a collection of markdown files that I'd like to become blog posts. In the course of trying to figure out how to filter by folder, I came across getNode() in various code samples, but I can't find anything about it the docs. It seems to be a part of the boundActionCreators inside onCreateNode, but I'm not 100% sure of that.

Can we add it to the docs? I'm happy to have a bash if somebody can point me the right direction.

EDIT: I realise that getNode looks like a sibling of boundActionCreators rather than a child of it.

[m-allanson]

@chmac Yes please, 👍 for additional docs.

getNode is defined here.

There's actually a bunch of helpers that get passed in to each gatsby-node.js API call. If you wanted to document any of those or just add placeholders, that'd be 👍 too.

Maybe this should be another page in the reference section of the docs, called Gatsby Node Utils? @KyleAMathews might have a better idea on where this should go and what to call it.

If the docs were to go in the reference section, you'd add a markdown file to the docs folder, and then reference it in doc-links.yaml.

Don't hesitate to ask questions at any point!

[KyleAMathews]

Yeah, we need a docs page for all the utils. We should build it like the other reference docs pages like adding jsdocs section to each utility and then querying them to create the page.

[vprasanth]

Hi folks, I'd be happy to help with this effort as well.

[m-allanson]

Good stuff @vprasanth!

gatsby-node.js API calls have the following args passed in by default:

• pathPrefix from _store_ (if available)

• boundActionCreators from src/redux/actions.js

• store, loadNodeContent, getNodes, getNode, hasNodeChanged, getNodeAndSavePathDependency from src/redux/index.js

• reporter from gatsby-cli/lib-reporter/index.js

• createNodeId from src/utils/create-node-id.js

• cache from src/utils/cache.js

@KyleAMathews What's the best way to document these? Should there be a reference page for the methods in src/redux/index.js? And then a separate reference page for anything from src/utils/* that should be documented?

[KyleAMathews]

It's best to have functions documented where they're defined. So let's add jsdocs comments there then when we create the page, we can query directly for the docs for the names of the functions we need https://github.com/gatsbyjs/gatsby/blob/c68d311fcaf06741b3b003f7076b07f4b75cac0d/www/src/pages/docs/bound-action-creators.js#L65

[KyleAMathews]

Thanks for jumping in to help @vprasanth! This has needed done for a while now 😅

[vprasanth]

Alright great, I think I understand. Thanks @m-allanson for doing that leg work :) I'll give it a shot tonight.

[vprasanth]

cc @KyleAMathews @m-allanson

Hey can someone take a quick look at this and let me know if I'm going generally in the right direction:

https://github.com/gatsbyjs/gatsby/compare/master...vprasanth:issue-4120

Thanks!

[KyleAMathews]

Looking good! Keep going and put a PR any time.

[m-allanson]

Thanks to @vprasanth for adding jsdocs for these methods. Reopening as the docs could still be exposed as part of gatsbyjs.org. See https://github.com/gatsbyjs/gatsby/issues/4120#issuecomment-370545006

[sanyaswain]

I'd like to take this up.

[jeffwillette]

@KyleAMathews I am a little confused about this. action-docs queries this-file that has all the actions defined in it and they have their jsdocs ready to go.

on the other hand node-api-docs query a file called node-api-docs which looks like a stub for all of the functions.

do the jsdocs need to go in the last file I linked to? or do they need to go somewhere else in the codebase?

[pieh]

I'd like to report some update on this - I started looking more into this and realized that our current jsdoc based generation won't handle things that we will need to properly display docs for node helpers (it is really focused on documenting functions/hooks). Here's my WIP branch https://github.com/gatsbyjs/gatsby/compare/master...pieh:gatsby-node-helpers?expand=1

And here's what it currently looks like with those changes (will definitely need some design modifications):

ATM I'm focusing on adding needed functionality, so help with documentation will still be needed

@deltaskelta we will create stub like file for it (like with node-api-docs), a lot of those utils need to be setup per plugin so we can't use actions route here

[gatsbot[bot]]

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!

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

[pieh]

After long time without updates on this - their is finally PR open https://github.com/gatsbyjs/gatsby/pull/12087 (there is preview link to new page in PR description). Any help with improving initial jsdocs I wrote for helpers is very welcome.