Gatsby: Document createPages formally

[dandv]

Summary

The documentation for createPages does not specify the parameters that createPages receives. Some of those parameters are glossed over in the example (actions), and some are omitted (reporter).

Since this is an API reference page (rather than the corresponding guide), I think the parameters should be comprehensively listed and documented.

Motivation

My particular motivation was to drill into the documentation for the graphql parameter and see if there was any way I could pass a context, in order to make authenticated GraphQL queries from gatsby-node. I couldn't figure out where the documentation for the graphql instance lives.

On the same page, createResolvers has a proper list of parameters.

[pieh]

You are right. We have separate page for arguments that are shared in all gatsby-node hooks ( https://www.gatsbyjs.org/docs/node-api-helpers/ ) but we don't reference it in actual gatsby-node API reference page.

It would be cumbersome to give full list of those for each hook, but we should have a note for each hook to check those shred ones + document any hook specific args (like graphql for createPages)

[pieh]

Also for reference - we generate API reference page from https://github.com/gatsbyjs/gatsby/blob/067468ac1043be3815683dd76c269f384b317ead/packages/gatsby/src/utils/api-node-docs.ts (and this is why createResolvers have params documented and createPages doesn't (because we don't have any @param jsdoc annotations in most of hooks)

[github-actions[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!
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! 💪💜

[github-actions[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 60 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.
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! 💪💜

[meganesu]

Adding some details so that hopefully this can be picked up by a community contributor for Hacktoberfest.

Steps to resolve this issue

• [ ] Add a note to the Node APIs doc (docs/docs/node-apis.md) about the shared arguments for all gatsby-node hooks.
  
  
  
  • This note should include a link to the separate page listing all the shared arguments (https://www.gatsbyjs.org/docs/node-api-helpers/).
  
  
• [ ] Add a @param for graphql to the jsdoc annotation for createPages (in gatsby/packages/gatsby/src/utils/api-node-docs.ts).

Open a pull request

• [ ] Open a pull request with your work including the words "closes #25805" in the pull request description

[veerreshr]

could I work on this issue?

[kalzen15]

Hi @meganesu!!!
I'd like to work on this issue.

[meganesu]

@veerreshr since you commented first, I'm going to assign this issue to you.

@kalzen15, thanks for your interest. We'd love to have you contribute on another one of our open issues!

Let me know if either of you have any questions!

[davad]

@veerreshr Do you still have time to work on this? If not, I'd like to.

[meganesu]

@davad since there hasn't been a response from @veerreshr, I'm going to go ahead an unassign them and assign this issue to you instead. Feel free to reach out if you have any questions!

[leonardotdleal]

Hi @meganesu !
I would like to work on this issue if @davad isn't :pray:

[davad]

Haha, give me a few more days @leonardotdleal :).

[davad]

I'm submitting a PR in a sec. There are a ton of props that are passed into the createPages call that we probably don't need to document.

I'm documenting actions, ~basePath,~ graphql, ~pathPrefix,~ and reporter. Are there any others we should include?

Edit: Not including basePath or pathPrefix because they seem confusing to explain and I'm not sure if users will get much use out of them.

Info on the full list of arguments follows

You can see the full object being constructed as apiCallArgs in /src/utils/api-runner-node.js (line 369 right now).

Here's the full object I see from a test run:

{traceId: "initial-createPages", waitForCascadingActions: true, parentSpan: Span, deferNodeMutation: true, graphql: ƒ, …}
actions: {deletePage: ƒ, createPage: ƒ, deleteNode: ƒ, deleteNodes: ƒ, createNode: ƒ, …}
basePath: ""
boundActionCreators: {deletePage: ƒ, createPage: ƒ, deleteNode: ƒ, deleteNodes: ƒ, createNode: ƒ, …}
cache: Cache {name: "default-site-plugin", store: {…}, cache: {…}}
createContentDigest: input => {…}
createNodeId: id => (0, _createNodeId.createNodeId)(id, plugin.name)
deferNodeMutation: true
emitter: {on: ƒ, off: ƒ, emit: ƒ}
getCache: name => {…}
getNode: id => _.store.getState().nodes.get(id)
getNodeAndSavePathDependency: (id, path) => {…}
getNodes: () => {…}
getNodesByType: type => {…}
graphql: (query, context) => {…}
hasNodeChanged: (id, digest) => {…}
loadNodeContent: async ƒ loadNodeContent(node)
parentSpan: Span {}
pathPrefix: ""
reporter: {stripIndent: ƒ, format: ƒ, setVerbose: ƒ, setNoColor: ƒ, panic: ƒ, …}
schema: {buildObjectType: ƒ, buildUnionType: ƒ, buildInterfaceType: ƒ, buildInputObjectType: ƒ, buildEnumType: ƒ, …}
store: {dispatch: ƒ, subscribe: ƒ, getState: ƒ, replaceReducer: ƒ, Symbol(observable): ƒ}
traceId: "initial-createPages"
tracing: {tracer: GlobalTracerDelegate, parentSpan: Span, startSpan: ƒ}
waitForCascadingActions: true
}