From f94d73f9516142f80de53c091069b6abba182d6c Mon Sep 17 00:00:00 2001 From: Nat Alison Date: Mon, 17 Feb 2020 11:48:16 -0800 Subject: [PATCH 1/3] split up graphql api fragments --- docs/docs/contentful-fragments.md | 7 +++++++ docs/docs/graphql-api.md | 29 +++------------------------- docs/docs/image-sharp-fragments.md | 9 +++++++++ www/src/data/sidebars/doc-links.yaml | 5 +++++ 4 files changed, 24 insertions(+), 26 deletions(-) create mode 100644 docs/docs/contentful-fragments.md create mode 100644 docs/docs/image-sharp-fragments.md diff --git a/docs/docs/contentful-fragments.md b/docs/docs/contentful-fragments.md new file mode 100644 index 0000000000000..56cd38f95a6ea --- /dev/null +++ b/docs/docs/contentful-fragments.md @@ -0,0 +1,7 @@ +--- +title: Contentful Fragments +jsdoc: ["gatsby-source-contentful/src/fragments.js"] +contentsHeading: Fragments +--- + +The following fragments are available in any site with `gatsby-source-contentful` installed and included in your `gatsby-config.js`. These fragments generally mirror the fragments outlined in the `gatsby-transformer-sharp` package. diff --git a/docs/docs/graphql-api.md b/docs/docs/graphql-api.md index d64f64ec91e0e..3d51e091e9449 100644 --- a/docs/docs/graphql-api.md +++ b/docs/docs/graphql-api.md @@ -231,33 +231,10 @@ For more information, check out the docs guide on [using fragments in Gatsby](/d Some fragments come included in Gatsby plugins, such as fragments for returning optimized image data in various formats with `gatsby-image` and `gatsby-transformer-sharp`, or data fragments with `gatsby-source-contentful`. -#### Image sharp fragments +Documentation on these fragments can be found in these pages: -The following fragments are available in any site with `gatsby-transformer-sharp` installed and included in your `gatsby-config.js`. - -Information on querying with these fragments is also listed in-depth in the [Gatsby image API docs](/docs/gatsby-image/), including options like resizing and recoloring. - - - {data => ( - - )} - - -#### Contentful fragments - -The following fragments are available in any site with `gatsby-source-contentful` installed and included in your `gatsby-config.js`. These fragments generally mirror the fragments outlined in the `gatsby-transformer-sharp` package. - - - {data => ( - - )} - +- [Image Sharp Fragments](/docs/image-sharp-fragments/) +- [Contentful Fragments](/docs/contentful-fragments/) **Note**: the above fragments are from officially maintained Gatsby starters; other plugins like `gatsby-source-datocms` and `gatsby-source-sanity` ship with fragments of their own. A list of those fragments can be found in the [`gatsby-image` README](/packages/gatsby-image#fragments). diff --git a/docs/docs/image-sharp-fragments.md b/docs/docs/image-sharp-fragments.md new file mode 100644 index 0000000000000..39fa121623ac5 --- /dev/null +++ b/docs/docs/image-sharp-fragments.md @@ -0,0 +1,9 @@ +--- +title: Image Sharp Fragments +jsdoc: ["gatsby-transformer-sharp/src/fragments.js"] +contentsHeading: Fragments +--- + +The following fragments are available in any site with `gatsby-transformer-sharp` installed and included in your `gatsby-config.js`. + +Information on querying with these fragments is also listed in-depth in the [Gatsby image API docs](/docs/gatsby-image/), including options like resizing and recoloring. diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 5a694c1559490..7b9ed837cc3bc 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -537,6 +537,11 @@ link: /docs/actions/ - title: GraphQL API link: /docs/graphql-api/ + items: + - title: Image Sharp Fragments + link: /docs/image-sharp-fragments/ + - title: Contentful Fragments + link: /docs/contentful-fragments/ - title: Gatsby Node APIs link: /docs/node-apis/ - title: Gatsby Node Helpers From e695117e3cfbdf07dfcf2a16959846ba5042ea74 Mon Sep 17 00:00:00 2001 From: Nat Alison Date: Mon, 17 Feb 2020 12:37:01 -0800 Subject: [PATCH 2/3] stopgap to display the fragments --- docs/docs/contentful-fragments.md | 1 + docs/docs/image-sharp-fragments.md | 1 + www/src/templates/template-api-markdown.js | 13 ++++++++++--- 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/docs/contentful-fragments.md b/docs/docs/contentful-fragments.md index 56cd38f95a6ea..6bd9334ad9e64 100644 --- a/docs/docs/contentful-fragments.md +++ b/docs/docs/contentful-fragments.md @@ -2,6 +2,7 @@ title: Contentful Fragments jsdoc: ["gatsby-source-contentful/src/fragments.js"] contentsHeading: Fragments +includeTopLevel: true --- The following fragments are available in any site with `gatsby-source-contentful` installed and included in your `gatsby-config.js`. These fragments generally mirror the fragments outlined in the `gatsby-transformer-sharp` package. diff --git a/docs/docs/image-sharp-fragments.md b/docs/docs/image-sharp-fragments.md index 39fa121623ac5..228527133c644 100644 --- a/docs/docs/image-sharp-fragments.md +++ b/docs/docs/image-sharp-fragments.md @@ -2,6 +2,7 @@ title: Image Sharp Fragments jsdoc: ["gatsby-transformer-sharp/src/fragments.js"] contentsHeading: Fragments +includeTopLevel: true --- The following fragments are available in any site with `gatsby-transformer-sharp` installed and included in your `gatsby-config.js`. diff --git a/www/src/templates/template-api-markdown.js b/www/src/templates/template-api-markdown.js index 837976caf1d8a..5d22fd4ad5877 100644 --- a/www/src/templates/template-api-markdown.js +++ b/www/src/templates/template-api-markdown.js @@ -39,12 +39,14 @@ const normalizeGatsbyApiCall = array => return { name: entry.name, codeLocation } }) -const mergeFunctions = (data, context) => { +const mergeFunctions = (data, context, includeTopLevel) => { const normalized = normalizeGatsbyApiCall(data.nodeAPIs.group) const docs = data.jsdoc.nodes.reduce((acc, node) => { const doc = node.childrenDocumentationJs - .filter(def => def.kind !== `typedef` && def.memberof) + .filter( + def => def.kind !== `typedef` && (includeTopLevel || def.memberof) + ) .map(def => { if (!context.apiCalls) { // When an api call list is not available, the line numbers from jsdoc @@ -81,7 +83,11 @@ export default function APITemplate({ data, location, pageContext }) { const page = data.mdx // Cleanup graphql data for usage with API rendering components - const mergedFuncs = mergeFunctions(data, pageContext) + const mergedFuncs = mergeFunctions( + data, + pageContext, + page.frontmatter.includeTopLevel + ) const description = page.frontmatter.description || page.excerpt return ( @@ -159,6 +165,7 @@ export const pageQuery = graphql` description contentsHeading showTopLevelSignatures + includeTopLevel } ...MarkdownPageFooterMdx } From 61d8e69afcd8ec70d9022f18232858e43d3aab1d Mon Sep 17 00:00:00 2001 From: Nat Alison Date: Mon, 17 Feb 2020 12:38:05 -0800 Subject: [PATCH 3/3] delete static query file --- .../api-reference/doc-static-queries.js | 52 ------------------- 1 file changed, 52 deletions(-) delete mode 100644 www/src/components/api-reference/doc-static-queries.js diff --git a/www/src/components/api-reference/doc-static-queries.js b/www/src/components/api-reference/doc-static-queries.js deleted file mode 100644 index 18d16e97d3394..0000000000000 --- a/www/src/components/api-reference/doc-static-queries.js +++ /dev/null @@ -1,52 +0,0 @@ -import React from "react" -import { graphql, StaticQuery } from "gatsby" - -export const DocumentationAndApiFragment = graphql` - fragment DocFragment on DocumentationJs { - availableIn - codeLocation { - start { - line - } - end { - line - } - } - ...DocumentationFragment - } -` - -// data for the graphql-api page -export const GraphqlApiQuery = ({ children }) => ( - children(data)} - /> -)