Create docs site (#401)

📝 Description
Create a new docs site with docusaurus. This is the first pass at copying the content over from the README. We will probably have to modify content but since this does not impact the library I think we can merge to get the setup running then edit pages as we see issues.

You can see the running example here: https://experdelfavero.github.io/graphql-kotlin/

Author: smyrick

.github/CODE_OF_CONDUCT.md

@@ -38,7 +38,7 @@ behaviour and are expected to take appropriate and fair corrective action in
 response to any instances of unacceptable behaviour.
 
 Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
+reject comments, commits, code, wiki or documentation edits, issues, and other contributions
 that are not aligned to this Code of Conduct, or to ban temporarily or
 permanently any contributor for other behaviours that they deem inappropriate,
 threatening, offensive, or harmful.

.gitignore

@@ -3,3 +3,9 @@
 .DS_Store
 target
 pom.xml.versionsBackup
+
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*

CONTRIBUTING.md

@@ -53,7 +53,9 @@ mvn antrun:run@detekt
 
 ## Add documentation for new or updated functionality
 
-Please add appropriate javadocs in the source code and ask the maintainers to update the wiki with any relevant information.
+Please add appropriate javadocs in the source code and ask the maintainers to update the documentation with any relevant
+information.
+Further instructions on how to add documentation content are in `webserver/README.md`.
 
 ## Add license information
 All source files must contain the following license header. If you are using an IDE please add this as a copyright template for this project so that it will be added automatically.

README.md

@@ -51,9 +51,11 @@ type Widget {
 
 ## 📋 Documentation
 
-Examples and documentation are available on our [Uncyclo](https://github.com/ExpediaGroup/graphql-kotlin/wiki) or in each module README file.
+Examples and documentation are available on our
+[documentation](https://ExpediaGroup.github.io/graphql-kotlin/docs/doc-main),
+or in each module README file.
 
-If you have a question about something you can not find in our wiki, the indivdual modules, or javadocs, feel free to [create an issue](https://github.com/ExpediaGroup/graphql-kotlin/issues) and tag it with the question label.
+If you have a question about something you can not find in our documentation, the indivdual modules, or javadocs, feel free to [create an issue](https://github.com/ExpediaGroup/graphql-kotlin/issues) and tag it with the question label.
 
 ## 👥 Contact
 

docs/contributors/release-proc.md

@@ -0,0 +1,15 @@
+---
+id: release-proc
+title: Releasing a new version
+---
+1. The `pom.xml` should already be `${currentVersion}-SNAPSHOT`
+
+2. Draft a new release and tag the commit (usually just `master`) you want to release as `${currentVersion}` or
+   increment to a new major/minor version https://github.com/ExpediaDotCom/graphql-kotlin/releases
+    - When drafting a new release, look at the commit history and comment any new features that were made
+    - Travis will automatically build on a new tag, change the pom to remove `-SNAPSHOT`, and push the library to Maven
+      Central
+    - Travis will create a new branch that bumps the version in both the library and example to
+      `${nextVersion}-SNAPSHOT`
+
+3. Create a new PR for the Travis branch for the snapshot updates

docs/doc-main.md

@@ -0,0 +1,25 @@
+---
+id: doc-main
+title: GraphQL-Kotlin User Guide
+---
+
+GraphQL Kotlin consists of number of libraries that aim to simplify GraphQL integration for Kotlin applications.
+
+## 📦 Modules
+
+* [graphql-kotlin-federation](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-federation)
+  — Schema generator extension to build federated GraphQL schemas
+* [graphql-kotlin-schema-generator](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-schema-generator)
+  — Code only GraphQL schema generation for Kotlin
+* [graphql-kotlin-spring-server](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/graphql-kotlin-spring-server)
+  — Spring Boot auto-configuration library to create GraphQL web app
+* [examples](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples)
+  — Example apps that use graphql-kotlin libraries to test and demonstrate usages
+
+If you encounter any problems using this library please open up a new
+[Issue](https://github.com/ExpediaGroup/graphql-kotlin/issues)
+
+Additional resources
+
+* [GraphQL](https://graphql.org/)
+* [graphql-java](https://www.graphql-java.com/documentation/)

docs/examples/examples.md

@@ -0,0 +1,25 @@
+---
+id: examples
+title: Examples of how to use the libraries
+---
+
+## Spring Example
+
+One way to run a GraphQL server is with [Spring Boot](https://github.com/spring-projects/spring-boot). A sample Spring
+Boot app that uses [Spring
+Webflux](https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html) together with
+`graphql-kotlin-schema-generator` and [graphql-playground](https://github.com/prisma/graphql-playground) is provided as
+a [examples/spring](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/spring). All the examples used
+in this documentation should be available in the sample app.
+
+In order to run it you can run
+[Application.kt](https://github.com/ExpediaDotCom/graphql-kotlin/blob/master/graphql-kotlin-spring-example/src/main/kotlin/com/expedia/graphql/sample/Application.kt)
+directly from your IDE. Alternatively you can also use the Spring Boot maven plugin by running `mvn spring-boot:run`
+from the command line. Once the app has started you can explore the example schema by opening Playground endpoint at
+[http://localhost:8080/playground](http://localhost:8080/playground).
+
+## Federation Example
+
+Example Spring Boot apps generating Federated GraphQL schema and Apollo Gateway that exposes single federated schema are
+provided in [examples/federation](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/federation)
+project. Please refer to their README files for details on how to run the target applications.

docs/execution/async-models.md

@@ -0,0 +1,103 @@
+---
+id: async-models
+title: Async Models
+---
+By default, `graphql-kotlin-schema-generator` will resolve all functions synchronously, i.e. it will block the
+underlying thread while executing the target function. While you could configure your GraphQL server with execution
+strategies that execute each query in parallel on some thread pools, instead we highly recommend to utilize asynchronous
+programming models.
+
+## Coroutines
+
+`graphql-kotlin-schema-generator` has built-in support for Kotlin coroutines. Provided default
+[FunctionDataFetcher](https://github.com/ExpediaDotCom/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expedia/graphql/execution/FunctionDataFetcher.kt)
+will automatically asynchronously execute suspendable functions and convert the result to `CompletableFuture` expected
+by `graphql-java`.
+
+Example
+
+```kotlin
+data class User(val id: String, val name: String)
+
+class Query {
+    suspend fun getUser(id: String): User {
+        // Your coroutine logic to get user data
+    }
+}
+```
+
+will produce the following schema
+
+```graphql
+
+schema {
+  query: Query
+}
+
+type Query {
+  getUser(id: String!): User
+}
+
+type User {
+  id: String!
+  name: String!
+}
+```
+
+## CompletableFuture
+
+`graphql-java` relies on Java `CompletableFuture` for asynchronously processing the requests. In order to simplify the
+interop with `graphql-java`, `graphql-kotlin-schema-generator` has a built-in hook which will automatically unwrap a
+`CompletableFuture` and use the inner class as the return type in the schema.
+
+```kotlin
+data class User(val id: String, val name: String)
+
+class Query {
+    fun getUser(id: String): CompletableFuture<User> {
+        // Your logic to get data asynchronously
+    }
+}
+```
+
+will result in the exactly the same schema as in the coroutine example above.
+
+## RxJava/Reactor
+
+If you use a different monad type, like `Single` from [RxJava](https://github.com/ReactiveX/RxJava) or `Mono` from
+[Project Reactor](https://projectreactor.io/), you just have to provide the logic in
+`SchemaGeneratorHooks.willResolveMonad` to unwrap it and return the inner class.
+
+```kotlin
+class RxJava2Query {
+    fun asynchronouslyDo(): Observable<Int> = Observable.just(1)
+
+    fun asynchronouslyDoSingle(): Single<Int> = Single.just(1)
+
+    fun maybe(): Maybe<Int> = Maybe.empty()
+}
+
+private class MonadHooks : SchemaGeneratorHooks {
+    override fun willResolveMonad(type: KType): KType = when (type.classifier) {
+        Observable::class, Single::class, Maybe::class -> type.arguments.firstOrNull()?.type
+        else -> type
+    } ?: type
+}
+
+val configWithRxJavaMonads = getConfig(hooks = MonadHooks())
+
+toSchema(queries = listOf(TopLevelObject(RxJava2Query())), config = configWithRxJavaMonads)
+```
+
+This will produce
+
+```graphql
+type Query {
+  asynchronouslyDo(): Int
+  asynchronouslyDoSingle(): Int
+  maybe: Int
+}
+```
+
+You can find additional example on how to configure the hooks in our [unit
+tests](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/test/kotlin/com/expediagroup/graphql/generator/SchemaGeneratorAsyncTests.kt).

docs/execution/data-fetching-environment.md

@@ -0,0 +1,29 @@
+---
+id: data-fetching-environment 
+title: Data Fetching Environment
+---
+Each resolver has a `DataFetchingEnvironment` that can be accessed from graphql-java:
+https://www.graphql-java.com/documentation/v13/data-fetching/
+
+You can access this info by including the `DataFetchingEnvironment` as one of the arguments to a Kotlin function. This
+argument will not be included in the schema.
+
+```kotlin
+class Query {
+    fun printEnvironmentInfo(environment: DataFetchingEnvironment, value: Int): String {
+        // Access env data
+    }
+}
+```
+
+This will produce the following schema
+
+```graphql
+type Query {
+  printEnvironmentInfo(value: Int!): String!
+}
+```
+
+You can also use this to retrieve arguments and query information from higher up the query chain. You can see a working
+example in the `graphql-kotlin-spring-example` module
+[[link](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/examples/spring/src/main/kotlin/com/expediagroup/graphql/sample/query/EnvironmentQuery.kt#L32)].

docs/execution/subscriptions.md

@@ -0,0 +1,43 @@
+---
+id: subscriptions
+title: Subscriptions
+---
+Subscriptions are supported with `graphql-java`. See their documentation first:
+https://www.graphql-java.com/documentation/v11/subscriptions/
+
+To make a function a subscription function you just have to have the return type wrapped in an implementation of a
+reactive-streams `Publisher`. As an example here is a function that uses Spring WebFlux to return a random number every
+second. Since `Flux` is an implementation of `Publisher` this is a valid method.
+
+```kotlin
+@GraphQLDescription("Returns a random number every second")
+fun counter(): Flux<Int> = Flux.interval(Duration.ofSeconds(1)).map { Random.nextInt() }
+```
+
+Then in the `toSchema` method you just have to provide a `List<TopLevelObject>` the same way as queries and mutations
+are provided with the `subscriptions` argument.
+
+```kotlin
+toSchema(
+    config = schemaConfig,
+    queries = queries.toTopLevelObjects(),
+    mutations = mutations.toTopLevelObjects(),
+    subscriptions = subscriptions.toTopLevelObjects()
+)
+```
+
+### Subscription Hooks
+
+Through the hooks a new method was added `didGenerateSubscriptionType` which is called after a new subscription type is
+generated but before it is added to the schema. The other hook are still called so you can add logic for the types and
+validation of subscriptions the same as queries and mutations.
+
+### Server Implementation
+
+The server that runs your GraphQL schema will have to support some method for subscriptions, like WebSockets.
+`graphql-kotlin-spring-server` provides default WebSocket based implementation and you can see an example implementation
+of a `Subscription` in the [example
+app](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/examples/spring/src/main/kotlin/com/expediagroup/graphql/sample/subscriptions/SimpleSubscription.kt).
+
+> NOTE: make sure that your implementation supports the `graphql-ws` sub-protocol which requires you handle some
+> specific websocket events.