Initial commit of documentation website (#164)

.gitignore

@@ -70,4 +70,11 @@ $RECYCLE.BIN/
 resources/META-INF/dist/
 
 .gradle
-build
+build
+
+# documentation website
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*

docs/2.0/Developer-Guide.md → docs/developer-guide.md

@@ -1,4 +1,8 @@
-# Developer Guide for JS GraphQL IntelliJ Plugin v2
+---
+id: developer-guide
+title: Developer guide
+sidebar_label: Developer guide
+---
 
 This developer guide covers how to setup your project to get the most out of the GraphQL language tooling in this plugin.
 
@@ -16,7 +20,7 @@ The most important aspect of using the plugin is to configure how schema types a
 If the schema types are not discovered correctly, language features such as completion and error highlighting
 will be based on the wrong type information.
 
-Schemas and their types are declared using [GraphQL Type System Definition Language](http://facebook.github.io/graphql/June2018/#sec-Type-System)
+Schemas and their types are declared using [GraphQL Type System Definition Language](https://graphql.github.io/graphql-spec/June2018/#sec-Type-System)
 which is also widely known as GraphQL Schema Definition Language (often abbreviated as SDL).
 
 If you're authoring your schemas in SDL, the plugin provides the following features:
@@ -42,68 +46,39 @@ scope is to prevent types from being picked up in more than one GraphQL type reg
 errors as types appear to have been declared more than once. In addition, the scopes prevent non-conflicting types from
 showing up in completions and ensure that validation only recognizes the types that belong to the current schema.
 
-The plugin allows you to configure your schema scopes in two different ways:
+The plugin allows you to configure your schema scopes using [graphql-config](https://github.com/prismagraphql/graphql-config) configuration files with `includes` and `excludes` glob patterns
 
-- Using the IDE "Settings" page called "Appearance & Behaviour" > ["Scopes"](https://www.jetbrains.com/help/idea/2018.1/settings-scopes.html) with patterns for inclusion and exclusion
-- Using [graphql-config](https://github.com/prismagraphql/graphql-config) configuration files with `includes` and `excludes` glob patterns 
+### Example projects ###
 
-### Setting up Multi-schema Projects using "Appearance & Behaviour" > "Scopes"
-In a multi-schema project, each schema needs its own separate scope.
-
-The recommended structure for multi-schema projects is to place each schema in a separate project module or folder.
-
-For example:
-
-```
-- project root/
-    - product a (schema one)/
-        - schema files and graphql aware components
-    - product b (schema two)/
-        - schema files and graphql aware components
-```
-
-With this structure there is no need to use exclude patterns.
-
-To setup the project, Open "Settings" > "Language & Frameworks" > "GraphQL" and select the "Multiple schemas".
-
-The scopes can be created via the "Edit scopes" link:
-
-- Click "Add scope"
-- Click Shared scope
-- Name it the same as the folder
-- Select "Project" in the drop down above the project tree
-- Select the "product a (schema one)" folder and click the "Include Recursively" button on the right
-- Repeat for other schemas
-
-Given a file which contains GraphQL, the plugin finds the first matching schema scope based on the file name, and then
-proceeds with schema discovery by processing only the files that the scope accepts.
-
-__Points to consider__:
-- You don't have to restrict the patterns to specific file extensions since the plugin only searches relevant file types
-- If you do limit to file extensions, make sure you include file extensions for components that use injected GraphQL, e.g. `.jsx`
-- When adding scopes, use the "Shared" scopes to create scopes that can be checked into source control and used by other
-  developers on the project
-- If you have created scopes for uses other than GraphQL schema discovery, you should place the GraphQL scopes at the top
-  of the list since the first matching scope is used by this plugin  
+See https://github.com/jimkyndemeyer/graphql-config-examples for example uses of `.graphqlconfig` to control schema discovery.
 
 ### Setting up Multi-schema Projects using graphql-config
-The second option for multi-schema projects is graphql-config. With graphql-config you don't get the scopes UI which
-displays the files in the scopes, but it may be the better option if you use other tools that support graphql-config.
-
-To setup the project, Open "Settings" > "Language & Frameworks" > "GraphQL" and select the "graphql-config".
-
 Please familiarize yourself with the [graphql-config format](https://github.com/prismagraphql/graphql-config/blob/master/specification.md)
 before proceeding.
 
 The next step is to decide where to place the `.graphqlconfig` file. The config file controls schema discovery from the
 directory it's placed in, as well as any sub folders that don't have their own `.graphqlconfig`.
 
-To create a `.graphqlconfig` file, right click a folder and select "New GraphQL Configuration File".
+To create a `.graphqlconfig` file, right click a folder and select "New GraphQL Configuration File" or use the "+" Button in the GraphQL Tool window tab called "Schemas and Project Structure".
 
 Depending on your preference, you can use a single `.graphqlconfig` file in a folder that is a parent to each schema
 folder, or you can place `.graphqlconfig` files in each schema folder.
 
-__Option A: Single config file:__
+__Option A: Multiple config files (recommended):__
+
+```
+- project root/
+    - product a (schema one)/
+        - .graphqlconfig <-----
+        - schema files and graphql aware components
+    - product b (schema two)/
+        - .graphqlconfig <-----
+        - schema files and graphql aware components
+```
+
+With this approach the location of the config files creates separate scopes for the two schemas. 
+
+__Option B: Single config file:__
 
 ```
 - project root/
@@ -129,19 +104,6 @@ With a single config file you need to separate the schemas using the `includes`
 }
 ```
 
-__Option B: Multiple config files:__
-
-```
-- project root/
-    - product a (schema one)/
-        - .graphqlconfig <-----
-        - schema files and graphql aware components
-    - product b (schema two)/
-        - .graphqlconfig <-----
-        - schema files and graphql aware components
-```
-
-With this approach the location of the config files creates separate scopes for the two schemas. 
 
 ### Working with GraphQL Endpoints and Scratch Files
 
@@ -156,16 +118,26 @@ toolbar button in the top left side of the scratch file editor.
 See https://github.com/prisma/graphql-config#specifying-endpoint-info for the expected format of endpoint details such as
 the URL, headers etc.
 
-GraphQL scratch files use the following rules for schema discovery and endpoints:
+The following example is from [graphql-config-examples/remote-schema-introspection](https://github.com/jimkyndemeyer/graphql-config-examples/tree/master/remote-schema-introspection)
+
+It demonstrates how to use the endpoints configured in `.graphqlconfig` to fetch an existing remote schema.
+
+![](assets/graphql-config-introspect.png)
+
+With `introspect: true` the plugin asks at project startup whether to update the local schema using the configured endpoint.
+
+![](assets/introspect-startup.png)
+
+The update works by sending an introspection query to the endpoint, and then writing the result to the configured `schemaPath`.
+
+The latest introspection query can easily be re-run using the schemas panel:
 
-- If there is a single `.graphqlconfig` the scratch file automatically uses the schema and endpoints from that configuration
-- For a project with multiple `.graphqlconfig` files, add the following GraphQL comment to your scratch file to pick the relevant `.graphqlconfig`:
-    - `# .graphqlconfig=<absolute path to your config dir>\.graphqlconfig`
-- In case no matching `.graphqlconfig` was found, the project base dir will be used for schema discovery, and no endpoints
-    will be available for queries or other operations   
+![](assets/introspect-re-run.png)
 
-### ---- TODO BELOW THIS LINE ----
+Introspection queries can also be executed by double-clicking endpoints in the schemas tree view:
 
-## Breaking changes from v1
+![](assets/introspect-endpoint.png) 
 
-## Troublshooting
+__Notes and comments__
+- If you're both developing the server schema and consuming it in a client, e.g. via component queries, you'll get the best tooling by having your schema expressed using GraphQL Schema Definition Language directly in your project. With that setup the plugin immediately discovers your schema, and you don't have to perform an introspection after server schema changes.
+- Tip: The re-run introspection action can be bound to a keyboard shortcut for convienience

docs/getting-started.md

@@ -0,0 +1,28 @@
+---
+id: getting-started
+title: Prerequisites & Installation
+sidebar_label: Prerequisites & Installation
+---
+
+## Prerequisites
+
+The plugin and this documentation site assumes you are already familiar with the GraphQL language. If you're not, please
+visit the official [graphql.org](https://graphql.org/) website first.
+
+The plugin works out of the box with popular GraphQL clients such as [Apollo GraphQL](https://www.apollographql.com/) and 
+[Relay](https://facebook.github.io/relay/), but you're free to choose your client and server frameworks. 
+
+## Installation
+
+The plugin is hosted in the JetBrains Plugin Repository at https://plugins.jetbrains.com/plugin/8097-js-graphql
+
+You can install it directly from your IDE via the "Settings > Plugins" screen.
+
+On the "Marketplace" tab simply search for "graphql" and select the "JS GraphQL" suggestion:
+
+![installation](assets/installation.png) 
+
+## Compatible IDEs and Versions
+
+The plugin works with all IDEs in the IntelliJ Platform, including but not limited to WebStorm, PhpStorm, IntelliJ IDEA, 
+and Android Studio. The minimum version is 2018.2 (182.711 or later).

docs/graphql-config-examples.md

@@ -0,0 +1,12 @@
+---
+id: graphql-config-examples
+title: Example Projects
+sidebar_label: Example Projects
+---
+
+Below you'll find examples that demonstrate how to set up your projects to get the most out of the plugin.
+
+## Project Structure and Schema Discovery
+
+See the [graphql-config-examples](https://github.com/jimkyndemeyer/graphql-config-examples/) repository which demonstrate
+how to setup schema discovery and endpoints using `.graphqlconfig` files.

website/blog/2019-03-31-blog-post.md

@@ -0,0 +1,11 @@
+---
+title: New Documentation Website
+author: Jim Kynde Meyer
+authorURL: https://twitter.com/jimmeyer
+---
+
+This site will provide documentation for working with JS GraphQL IntelliJ Plugin.  
+
+<!--truncate-->
+
+More documentation updates to follow once the 2.0 release is published.

website/core/Footer.js

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const React = require('react');
+
+class Footer extends React.Component {
+    docUrl(doc, language) {
+        const baseUrl = this.props.config.baseUrl;
+        const docsUrl = this.props.config.docsUrl;
+        const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`;
+        return `${baseUrl}${docsPart}${doc}`;
+    }
+
+    pageUrl(doc, language) {
+        const baseUrl = this.props.config.baseUrl;
+        return baseUrl + (language ? `${language}/` : '') + doc;
+    }
+
+    render() {
+        return (
+            <footer className="nav-footer" id="footer">
+                <section className="sitemap">
+                    <a href={this.props.config.baseUrl} className="nav-home">
+                        {this.props.config.footerIcon && (
+                            <img
+                                src={this.props.config.baseUrl + this.props.config.footerIcon}
+                                alt={this.props.config.title}
+                                width="66"
+                                height="58"
+                            />
+                        )}
+                    </a>
+                    <div>
+                        <h5>Docs</h5>
+                        <a href={this.docUrl('getting-started.html', this.props.language)}>
+                            Getting Started
+                        </a>
+                        <a href={this.docUrl('developer-guide.html', this.props.language)}>
+                            Developer guide
+                        </a>
+                        <a href={this.docUrl('graphql-config-examples.html', this.props.language)}>
+                            Example projects
+                        </a>
+                    </div>
+                    <div>
+                        <h5>Community</h5>
+                        <a href="https://graphql.org/"  target="_blank">
+                            graphql.org
+                        </a>
+                        <a href="https://github.com/graphql-java/graphql-java" target="_blank">
+                            graphql-java
+                        </a>
+                        <a href="https://github.com/prisma/graphql-config" target="_blank">
+                            graphql-config
+                        </a>
+                        <a href="https://github.com/chentsulin/awesome-graphql" target="_blank">
+                            awesome-graphql
+                        </a>
+                        <a href="https://twitter.com/search?q=graphql" target="_blank" rel="noreferrer noopener">
+                            Twitter
+                        </a>
+                        <a href="https://stackoverflow.com/questions/tagged/graphql" target="_blank" rel="noreferrer noopener">
+                            Stack Overflow
+                        </a>
+                    </div>
+                    <div>
+                        <h5>More</h5>
+                        <a href={`${this.props.config.baseUrl}blog`}>Blog</a>
+                        <a href="https://github.com/jimkyndemeyer/js-graphql-intellij-plugin">GitHub</a>
+                        <a
+                            className="github-button"
+                            href={this.props.config.repoUrl}
+                            data-icon="octicon-star"
+                            data-count-href="/jimkyndemeyer/js-graphql-intellij-plugin/stargazers"
+                            data-show-count="true"
+                            data-count-aria-label="# stargazers on GitHub"
+                            aria-label="Star this project on GitHub">
+                            Star
+                        </a>
+                    </div>
+                </section>
+                <section className="copyright">{this.props.config.copyright}</section>
+            </footer>
+        );
+    }
+}
+
+module.exports = Footer;

website/package.json

@@ -0,0 +1,14 @@
+{
+  "scripts": {
+    "examples": "docusaurus-examples",
+    "start": "docusaurus-start",
+    "build": "docusaurus-build",
+    "publish-gh-pages": "docusaurus-publish",
+    "write-translations": "docusaurus-write-translations",
+    "version": "docusaurus-version",
+    "rename-version": "docusaurus-rename-version"
+  },
+  "devDependencies": {
+    "docusaurus": "1.7.2"
+  }
+}