Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update GraphQL docs for Docusaurus graphql documentation generator plugin #11102

Merged
merged 4 commits into from
Jul 30, 2024
Merged

Update GraphQL docs for Docusaurus graphql documentation generator plugin #11102

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
015b90b
Update docusaurus package name
edno Jul 26, 2024
a03493d
Update graphql doc graphql-markdown configuration
edno Jul 26, 2024
8e3d308
fix extra ` for code in graphql.md
edno Jul 26, 2024
86793cf
Merge branch 'main' into patch-1
Josh-Walker-GM Jul 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 9 additions & 37 deletions docs/docs/graphql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2043,7 +2043,7 @@ Orm if you want a custom mask:
}
```

``Cannot query field "sta" on type "Media". [REDACTED]?`
`Cannot query field "sta" on type "Media". [REDACTED]?`


### Error Masking
Expand Down Expand Up @@ -2343,11 +2343,11 @@ The documentation generated is present when exploring the schema.

### Use in Docusaurus

If your project uses [Docusaurus](https://docusaurus.io), the generated commented SDL can be used to publish documentation using the [graphql-markdown](https://graphql-markdown.github.io) plugin.
If your project uses [Docusaurus](https://docusaurus.io), the generated commented SDL can be used to publish documentation using the [graphql-markdown](https://graphql-markdown.dev/) plugin.

#### Basic Setup

The following is some basic setup information, but please consult [Docusaurus](https://docusaurus.io) and the [graphql-markdown](https://graphql-markdown.github.io) for latest instructions.
The following is some basic setup information, but please consult [Docusaurus](https://docusaurus.io) and the [graphql-markdown](https://graphql-markdown.dev/) for latest instructions.

1. Install Docusaurus (if you have not done so already)

Expand Down Expand Up @@ -2378,7 +2378,7 @@ mkdir docs // if needed
3. Install the GraphQL Generators Plugin

```terminal
yarn workspace docs add @edno/docusaurus2-graphql-doc-generator graphql
yarn workspace docs add @graphql-markdown/docusaurus graphql @graphql-tools/graphql-file-loader
```

4. Ensure a Directory for your GraphQL APi generated documentation resides in with the Docusaurus directory `/docs` structure
Expand All @@ -2399,12 +2399,15 @@ mkdir docs/graphql-api // if needed
// ...
plugins: [
[
'@edno/docusaurus2-graphql-doc-generator',
'@graphql-markdown/docusaurus',
{
schema: '../.redwood/schema.graphql',
rootPath: './docs',
baseURL: 'graphql-api',
linkRoot: '../..',
loaders: {
GraphQLFileLoader: '@graphql-tools/graphql-file-loader',
},
},
],
],
Expand All @@ -2426,37 +2429,6 @@ themeConfig:
},
//...
```
6. Update `docs/sidebars.js` to include the generated `graphql-api/sidebar-schema.js`

```
// docs/sidebars.js
/**
* Creating a sidebar enables you to:
* - create an ordered group of docs
* - render a sidebar for each doc of that group
* - provide next/previous navigation
*
* The sidebars can be generated from the filesystem, or explicitly defined here.
*
* Create as many sidebars as you want.
*/

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
// By default, Docusaurus generates a sidebar from the docs folder structure
tutorialSidebar: [
{
type: 'autogenerated',
dirName: '.',
},
],
...require('./docs/graphql-api/sidebar-schema.js'),
}

module.exports = sidebars
```

7. Generate the docs

Expand All @@ -2465,7 +2437,7 @@ module.exports = sidebars
:::tip
You can overwrite the generated docs and bypass the plugin's diffMethod use `--force`.

``yarn docusaurus graphql-to-doc --force`
`yarn docusaurus graphql-to-doc --force`
:::

8. Start Docusaurus
Expand Down