npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@graphidocs/docs

v1.0.6

Published

Static page generator for documenting GraphQL Schema

Downloads

496

Readme

Static page generator for documenting GraphQL Schema

Build Status Coverage Status npm (scoped) GitHub tag

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.4

    Usage: node bin/graphidocs.ts [OPTIONS] 

    
    PTIONS]:
    -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=classic].
    -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

You can specify which template to use via the CLI:

    > graphidocs -t classic \
                -s ./schema.json -o ./doc/schema

Or via 'package.json':

     // package.json

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

The current built-in templates are:

  • classic

Relative Path

The template can also take a relative path (from where command is executed):

    > graphidocs -t ./my-template \
                -s ./schema.json -o ./doc/schema
     // package.json

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

Node Module

To specify a node module as a template, specify the name as the template:

    > graphidocs -t my-graphidocs-template \
                -s ./schema.json -o ./doc/schema
     // package.json

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

Create a Template

All rendering is done within the template. It's up to the template to pick what and how to render. In order to render, you should extend the Template class. There are a few methods you must use:

  • getTemplateFiles A way to get all the template files. Should return a promise of strings to the files.
  • serialize The method that will turn the data into text that will get written out.
  • renderDirective The method that will render the GraphQL directives.
  • renderIndex The method that will render the index file like index.html.
  • renderType The method that will render the GraphQL types.

An example of this is (from the classic toolkit):

import * as glob from 'glob';
import { render } from 'mustache';
import { TypeRef } from '../../lib/interface';
import Template, { ITemplateFileMap } from '../../lib/Template';
import { getFilenameOf } from '../../lib/utility';
import { ITemplateData } from '../../lib/utility/template';

export default class ClassicTemplate extends Template {
  public async getTemplateFiles(): Promise<string[]> {
    return new Promise<string[]>((resolve, reject) => glob(
      '**/*.mustache',
      { cwd: __dirname },
      (error, files) => error ? reject(error) : resolve(files)
    ));
  }

  public serialize(templateData: ITemplateData, templateFiles: ITemplateFileMap): string {
    return render(templateFiles.index, templateData, templateFiles);
  }

  public renderDirective(type: TypeRef): Promise<void> {
    return this.renderFile(getFilenameOf(type), type);
  }

  public renderIndex(): Promise<void> {
    return this.renderFile('index.html');
  }

  public renderType(type: TypeRef): Promise<void> {
    return this.renderFile(getFilenameOf(type), type);
  }
}

Contributors