fix(gatsby-source-wordpress): generate plugin options docs (#32856)

Author: TylerBarnes

packages/gatsby-source-wordpress/__tests__/docs-generation.test.js

@@ -0,0 +1,19 @@
+import { getPluginOptionsMdString } from "../generate-plugin-options-docs"
+import fs from "fs-extra"
+import path from "path"
+
+describe(`Plugin options docs`, () => {
+  test(`Docs have been generated by running "yarn build" or "yarn generate-plugin-options-docs"`, async () => {
+    const generatedDocsFileContents = await fs.readFile(
+      path.join(__dirname, `../docs/plugin-options.md`),
+      `utf-8`
+    )
+
+    const mdString = await getPluginOptionsMdString()
+
+    expect(generatedDocsFileContents).toBeTruthy()
+    expect(mdString).toBeTruthy()
+
+    expect(generatedDocsFileContents).toEqual(mdString)
+  })
+})

packages/gatsby-source-wordpress/generate-plugin-options-docs.js

@@ -8,7 +8,12 @@ const prettierConfig = require(`../../.prettierrc.js`)
 
 const {
   pluginOptionsSchema,
-} = require(`./dist/steps/declare-plugin-options-schema`)
+} = require(`./src/steps/declare-plugin-options-schema`)
+
+/**
+ * This script generates ./docs/plugin-options.md from the plugin options schema.
+ * ./docs/plugin-options.md should never be edited directly since it's auto-generated. Update ./src/steps/declare-plugin-options-schema.ts instead
+ */
 
 // :( poor children
 const excludeParentsChildren = [`RootQuery`]
@@ -135,7 +140,7 @@ function joiKeysToMD({
  *
  * @param {object} description
  */
-async function generateMdFileFromSchemaDescription(description) {
+async function generateMdStringFromSchemaDescription(description) {
   const template = Handlebars.compile(`# Plugin Options
 
 [comment]: # (This file is automatically generated. Do not edit it directly. Instead, edit the Joi schema in ./plugin/src/steps/declare-plugin-options-schema.js)
@@ -162,14 +167,28 @@ async function generateMdFileFromSchemaDescription(description) {
     docs,
   })
 
-  const mdContentsFormatted = prettier.format(mdContents, {
+  const mdStringFormatted = prettier.format(mdContents, {
     parser: `markdown`,
     ...prettierConfig,
   })
 
-  await fs.writeFile(`./docs/plugin-options.md`, mdContentsFormatted)
+  return mdStringFormatted
 }
 
-const description = pluginOptionsSchema({ Joi }).describe()
+async function getPluginOptionsMdString() {
+  const description = pluginOptionsSchema({ Joi }).describe()
+  const mdString = generateMdStringFromSchemaDescription(description)
+  return mdString
+}
+
+async function writePluginOptionsMdFile() {
+  console.info(`writing out plugin options schema docs to plugin-options.md`)
+  const mdString = await getPluginOptionsMdString()
+  await fs.writeFile(`./docs/plugin-options.md`, mdString)
+}
+
+if (process.env.NODE_ENV !== `test`) {
+  writePluginOptionsMdFile()
+}
 
-generateMdFileFromSchemaDescription(description)
+module.exports = { getPluginOptionsMdString }

packages/gatsby-source-wordpress/src/steps/declare-plugin-options-schema.ts renamed to packages/gatsby-source-wordpress/src/steps/declare-plugin-options-schema.js

@@ -1,7 +1,9 @@
-import { Step } from "./../utils/run-steps"
-import prettier from "prettier"
+/**
+ * This file is intentionally not TS so it can be run in a yarn script without being transpiled.
+ */
+const prettier = require(`prettier`)
 
-const wrapOptions = (innerOptions): string =>
+const wrapOptions = innerOptions =>
   prettier
     .format(
       `const something = {
@@ -14,8 +16,8 @@ const wrapOptions = (innerOptions): string =>
     .replace(`const something = `, ``)
     .replace(`;`, ``)
 
-export const pluginOptionsSchema: Step = ({ Joi }) => {
-  const getTypeOptions = (): any =>
+const pluginOptionsSchema = ({ Joi }) => {
+  const getTypeOptions = () =>
     Joi.object({
       where: Joi.string()
         .allow(null)
@@ -71,7 +73,7 @@ export const pluginOptionsSchema: Step = ({ Joi }) => {
         .allow(null)
         .allow(false)
         .description(
-          `Determines wether or not this type will be treated as an interface comprised entirely of other Gatsby node types.`
+          `Determines whether or not this type will be treated as an interface comprised entirely of other Gatsby node types.`
         )
         .meta({
           example: wrapOptions(`
@@ -156,7 +158,7 @@ export const pluginOptionsSchema: Step = ({ Joi }) => {
         showQueryVarsOnError: Joi.boolean()
           .default(false)
           .description(
-            `When a GraphQL error is returned and the process exits, this plugin option determines wether or not to log out the query vars that were used in the query that returned GraphQL errors.`
+            `When a GraphQL error is returned and the process exits, this plugin option determines whether or not to log out the query vars that were used in the query that returned GraphQL errors.`
           )
           .meta({
             example: wrapOptions(`
@@ -198,7 +200,7 @@ export const pluginOptionsSchema: Step = ({ Joi }) => {
         panicOnError: Joi.boolean()
           .default(false)
           .description(
-            `Determines wether or not to panic when any GraphQL error is returned.
+            `Determines whether or not to panic when any GraphQL error is returned.
 
 Default is false because sometimes non-critical errors are returned alongside valid data.`
           )
@@ -214,7 +216,7 @@ Default is false because sometimes non-critical errors are returned alongside va
         onlyReportCriticalErrors: Joi.boolean()
           .default(true)
           .description(
-            `Determines wether or not to log non-critical errors. A non-critical error is any error which is returned alongside valid data. In previous versions of WPGraphQL this was very noisy because trying to access an entity that was private returned errors.`
+            `Determines whether or not to log non-critical errors. A non-critical error is any error which is returned alongside valid data. In previous versions of WPGraphQL this was very noisy because trying to access an entity that was private returned errors.`
           )
           .meta({
             example: wrapOptions(`
@@ -828,7 +830,7 @@ This should be the full url of your GraphQL endpoint.`
               }),
             useIf: Joi.any()
               .description(
-                `A function used to determine wether or not to apply this plugin options preset. It should return a boolean value. True will cause the preset to apply, false will disclude it.`
+                `A function used to determine whether or not to apply this plugin options preset. It should return a boolean value. True will cause the preset to apply, false will disclude it.`
               )
               .default(`() => false`)
               .meta({
@@ -900,3 +902,7 @@ This should be the full url of your GraphQL endpoint.`
         .allow(null),
     })
 }
+
+module.exports = {
+  pluginOptionsSchema,
+}