graphdoc-plugin-operations

GraphQL schema HTML documentation generation, using graphdoc with Isolated Operations

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": "^$",
    "eraseByDescriptionRegex": "^$",
    "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:

Extracted Parameters Documentation

Extracted

Not 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

• Pokemon GraphQL schema: Project and Online generated documentation.
• Github GraphQL schema: Project and Online generated documentation.

Prerequisites

• "@2fd/graphdoc": "2.4.0".

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

Documentation

• Main documentation.

• CHANGELOG: contains the information about changes in each version, chronologically ordered (Keep a Changelog).

Contributing

• Use it.
• Share it.
• Give it a Star.
• Propose changes or improvements.
• Report bugs.

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.

Changelog

2.2.0 - June 2021

• Adds extractParametersDoc to allow moving parameters documentation from operation definition to operation description.
• Fixes double slash at baseUrl.
• Updates Documentation.