graphdoc-plugin-operations

GraphQL schema HTML documentation generation, using graphdoc with Isolated Operations

Usage no npm install needed!

<script type="module">
  import graphdocPluginOperations from 'https://cdn.skypack.dev/graphdoc-plugin-operations';
</script>

README


GraphQL schema HTML documentation generation, using graphdoc with Isolated Operations

graphdoc-plugin-operations graphdoc-plugin-operations License Github repo Gitlab repo

Quick Start

1 . Add dependencies:

package.json:

  "devDependencies": {
    "@2fd/graphdoc": "2.4.0",
    "graphdoc-plugin-operations": "2.2.0",
    "graphdoc-plugin-flexible": "1.0.2",

2 . If default options are not suitable, then configure graphdoc-plugin-operations:

package.json:

{
  "graphdoc-plugin-operations": {
    "documentTitle": "The Description",
    "navigationTitle": "The Operations",
    "eraseByNameRegex": "^someOperation\\w*",
    "eraseByDescriptionRegex": "@RemoveFromDocumentation",
    "extractParametersDoc": false,
    "enableAssets": false
  }
}

3 Use graphdoc-plugin-operations:

package.json:

  "scripts": {
    "doc": "graphdoc -p graphdoc/../../graphdoc-plugin-operations -p graphdoc/../../graphdoc-plugin-flexible  -p graphdoc/../../graphdoc-plugin-schema -s ./schema.graphql -o ./build/documentation"
  },
  "graphdoc-plugin-flexible": {
    "document.schema": { "disable": true }
  },
  "graphdoc-plugin-schema": {
    "enableAssets": false
  },
  "devDependencies": {
    "@2fd/graphdoc": "2.4.0",
    "graphdoc-plugin-flexible": "1.0.2",
    "graphdoc-plugin-operations": "2.2.0",
    "graphdoc-plugin-schema": "2.0.0",

graphdoc-plugin-flexible is required to disable document.schema plugin and allow custom types.
graphdoc-plugin-schema will substitute disabled document.schema plugin when required, and "enableAssets": false to avoid assets duplication.
graphdoc/../../ this is required to get external plugins working in graphdoc.

Goals

graphdoc-plugin-operations provides a way document operations independently using graphdoc.

Options

package.json:

(default values)

{
  "graphdoc-plugin-operations": {
    "documentTitle": "Description",
    "navigationTitle": "Operations",
    "eraseByNameRegex": "^quot;,
    "eraseByDescriptionRegex": "^quot;,
    "extractParametersDoc": true,
    "enableAssets": true
  }
}
  • documentTitle: title of the document section.
  • navigationTitle: title of the operations section in the navigation.
  • eraseByNameRegex: Regular Expression to be used to remove operations, based on name.
  • eraseByDescriptionRegex: Regular Expression to be used to remove operations, based on description.
  • extractParametersDoc: if set to false, parameters documentation will be stay on operation declaration.
  • enableAssets: if set to false, then it will disable all the assets provided by the plugin, i.e. script and css files will not be included.
    • graphdoc-plugin-operations uses exactly the same assets that graphdoc-plugin-schema and document-schema use.

The following shows where the documentTitle, the navigationTitle and the "code block" are located, using the example documentation created by graphdoc, Pokemon GraphQL HTML Documentation, using Pokemon GraphQL schema:

Graphdoc sections

Extracted Parameters Documentation

Extracted

extracted

Not Extracted

extracted

Using/Configuration

  • To use graphdoc-plugin-operations is necessary that document-schema plugin is disabled (since it doesn't allow custom types), use graphdoc-plugin-flexible plugin:

package.json

  "scripts": {
    "doc": "graphdoc -p graphdoc/../../graphdoc-plugin-operations  -p graphdoc/../../graphdoc-plugin-flexible -s ./schema.graphql -o ./build/documentation"
  },
  "devDependencies": {
    "@2fd/graphdoc": "2.4.0",
    "graphdoc-plugin-flexible": "1.0.2"
  },
  "graphdoc-plugin-flexible": {
    "document.schema": { "disable": true }
  },
  "devDependencies": {
    "@2fd/graphdoc": "2.4.0",
    "graphdoc-plugin-flexible": "1.0.2",
    "graphdoc-plugin-operations": "2.2.0",
    "graphdoc-plugin-schema": "2.0.0",

You can use graphdoc-plugin-schema plugin as an alternative to document-schema plugin.

  • main.mustache template may need some changes in other to get a better view, e.g.:

    {{#type}}
    {{^type.operationName}}<p class="slds-text-title--caps slds-text-color--weak">{{type.kind}}</p>{{/type.operationName}}
    {{#type.operationName}}<p class="slds-text-title--caps slds-text-color--weak">Operation</p>{{/type.operationName}}
    {{/type}}

Online Examples

Prerequisites

graphdoc can work with older versions of GraphQL (description syntax: #), and new versions (description syntax: """), How to configure graphdoc.

Documentation

Contributing

License

MIT License

Remember

  • Use code style verification tools => Encourages Best Practices, Efficiency, Readability and Learnability.
  • Code Review everything => Encourages Functional suitability, Performance Efficiency and Teamwork.
  • If viable, Start testing early => Encourages Reliability and Maintainability.

Additional words

Don't forget:

  • Love what you do.
  • Learn everyday.
  • Learn yourself.
  • Share your knowledge.
  • Think different!.
  • Learn from the past, dream on the future, live and enjoy the present to the max!.
  • Enjoy and Value the Quest (It's where you learn and grow).

At life:

  • Let's act, not complain.
  • Be flexible.

At work:

  • Let's give solutions, not questions.
  • Aim to simplicity not intellectualism.