graphdoc-plugin-flexible

GraphQL documentation with Flexible graphdoc

Usage no npm install needed!

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

README


GraphQL documentation with Flexible graphdoc

graphdoc-plugin-flexible graphdoc-plugin-flexible License Github repo Gitlab repo

Quick Start

1 . Add dependencies:

package.json:

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

2 . Configure graphdoc-plugin-flexible, e.g. without navigation.schema plugin:

package.json:

{
  "graphdoc-plugin-flexible": {
    "navigation.schema": {
      "disable": true
    }
  }
}

3 Use graphdoc-plugin-flexible:

package.json:

  "scripts": {
    "doc": "graphdoc -p graphdoc/../../graphdoc-plugin-flexible -s ./schema.graphql -o ./build/documentation"
  }

When using graphdoc-plugin-flexible, the graphdoc plugins must NOT be used, it will duplicate outputs.
graphdoc/../../ this is required to get external plugins working in graphdoc.

Goals

graphdoc-plugin-flexible provides a way to use graphdoc to create HTML documentation for GraphQL in an flexible way, i.e. if you use graphdoc with its default plugins, you will have to use it all, for navigation creation, for document creation and with all its assets, graphdoc-plugin-flexible plugin will allow to select which plugins you want to use from graphdoc, so use only what you need or use other plugins (e.g. graphdoc-plugin-operations) without overlapping.

Options

package.json:

(default values)

{
  "graphdoc-plugin-flexible": {
    "navigation.schema": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "navigation.scalar": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "navigation.enum": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "navigation.interface": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "navigation.union": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "navigation.object": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "navigation.input": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "navigation.directive": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "document.schema": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    },
    "document.require": {
      "disable": true,
      "navigations": false,
      "documents": false,
      "assets": false
    }
  }
}

The plugins provided by graphdoc are:

  • navigation.schema: Generates navigations for GraphQL schema.
  • navigation.scalar: Generates navigations for GraphQL scalar types.
  • navigation.enum: Generates navigations for GraphQL enum types.
  • navigation.interface: Generates navigations for GraphQL interface types.
  • navigation.union: Generates navigations for GraphQL union types.
  • navigation.object: Generates navigations for GraphQL object types.
  • navigation.input: Generates navigations for GraphQL input types.
  • navigation.directive: Generates navigations for GraphQL directives.
  • document.schema: Generates the HTML "Definition" section for any GraphQL element.
  • document.require: Generates HTML "Required By" section for any GraphQL element.

The following shows the sections worked by the graphdoc plugins, using the example created by graphdoc, Pokemon GraphQL:

Graphdoc sections

The options for the plugins are:

  • navigations: if set to false, then it will disable the navigation creation process of the plugin, i.e. plugin getNavigations will not be called.
  • documents: if set to false, then it will disable the document creation process of the plugin, i.e. plugin getDocuments will not be called.
  • assets: if set to false, then it will disable all the assets provided by the plugin, i.e. plugin getHeaders and getAssets will not be called.
  • disable: if set to true, then it will disable the plugin completely, i.e. equal to "navigations": false + "documents": false + "assets": false.

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.