Package Exports

@graphidocs/docs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@graphidocs/docs) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Static page generator for documenting GraphQL Schema

npm (scoped) GitHub tag

install
use
plugin
template
contributors

Install

    npm install -g @graphidocs/docs

Use

Generate documentation from live endpoint

    > graphidocs -e http://localhost:8080/graphql -o ./doc/schema

Generate documentation from IDL file

    > graphidocs -s ./schema.graphql -o ./doc/schema

Generate documentation from for the "modularized schema" of graphql-tools

    > graphidocs -s ./schema.js -o ./doc/schema

./schema.graphql must be able to be interpreted with graphql-js/utilities#buildSchema

Generate documentation from json file

    > graphidocs -s ./schema.json -o ./doc/schema

./schema.json contains the result of GraphQL introspection query

Puts the options in your `package.json`

     // package.json

    {
        "name": "project",
        // [...]
        "graphidocs": {
            "endpoint": "http://localhost:8080/graphql",
            "output": "./doc/schema",
        }
    }

And execute

    > graphidocs

Help

    > graphidocs -h
    
    Static page generator for documenting GraphQL Schema v1.0.0

    Usage: node bin/graphidocs.ts [OPTIONS] 

    
    [OPTIONS]:
    -c, --config                   Configuration file [./package.json].
    -e, --endpoint                 Graphql http endpoint ["https://domain.com/graphql"].
    -x, --header                   HTTP header for request (use with --endpoint). ["Authorization: Token cb8795e7"].
    -q, --query                    HTTP querystring for request (use with --endpoint) ["token=cb8795e7"].
    -s, --schema, --schema-file    Graphql Schema file ["./schema.json"].
    -p, --plugin                   Use plugins [default=graphidocs/plugins/default].
    -t, --template                 Use template [default=graphidocs/template/slds].
    -o, --output                   Output directory.
    -d, --data                     Inject custom data.
    -b, --base-url                 Base url for templates.
    -f, --force                    Delete outputDirectory if exists.
    -v, --verbose                  Output more information.
    -V, --version                  Show graphidocs version.
    -h, --help                     Print this help

Plugin

In graphidocs a plugin is simply an object that controls the content that is displayed on every page of your document.

This object should only implement the PluginInterface.

Make a Plugin

To create your own plugin you should only create it as a plain object or a constructor and export it as default

If you export your plugin as a constructor, when going to be initialized, will receive three parameters

schema: The full the result of GraphQL instrospection query
projectPackage: The content of package.json of current project (or the content of file defined with --config flag).
graphidocsPackag: The content of package.json of graphidocs.

For performance reasons all plugins receive the reference to the same object and therefore should not modify them directly as it could affect the behavior of other plugins (unless of course that is your intention)

Examples

    // es2015 export constructor
    export default class MyPlugin {
        constructor(schema, projectPackage, graphidocsPackage){}
        getAssets() { /* ... */ }
        /* ... */
    }

    // es2015 export plain object
    export default cost myPlugin = {
        getAssets() { /* ... */ },
        /* ... */
    }

    // export constructor
    function MyPlugin(schema, projectPackage, graphidocsPackage) { /* ... */ }

    MyPlugin.prototype.getAssets =  function() { /* ... */ };
    /* ... */

    exports.default = MyPlugin;

    // export plain object

    exports.default = {
        getAssets: function() { /* ... */ },
        /* ... */
    }

Use plugin

You can use the plugins in 2 ways.

Use plugins with command line

    > graphidocs -p graphidocs/plugins/default \
                -p some-dependencie/plugin \
                -p ./lib/plugin/my-own-plugin \
                -s ./schema.json -o ./doc/schema

Use plugins with `package.json`

     // package.json

    {
        "name": "project",
        // [...]
        "graphidocs": {
            "endpoint": "http://localhost:8080/graphql",
            "output": "./doc/schema",
            "plugins": [
                "graphidocs/plugins/default",
                "some-dependencie/plugin",
                "./lib/plugin/my-own-plugin"
            ]
        }
    }

Built-in plugin

TODO

Template

TODO

Release

To release to the npm registry, a travis job to deploy is setup to occur on a tag being pushed to the GitHub repo. We can use the npm version command that will increment the version in package.json and add a git tag. To handle this, there is a release.sh script. By default, this will increment the patch version:

./release.sh

If you want to define which version to increment, you can pass in an argument:

./release.sh major

If you wanted to take over exactly which version, you can use specify a semver:

./release.sh 1.1.1

This should automatically push the new tag to GitHub and a Travis build will get triggered. This will also use the NPM_API_KEY environment variable.

@graphidocs/docs