Consolidate compiler / workflow guides

Reviewed By: alunyov, kassens

Differential Revision: D26895903

fbshipit-source-id: 7c0c61bd99bcd9ca8cadaf5d1a39a98c9cebafe4

website-v2/docs/api-reference/graphql/graphql-directives.md

@@ -7,7 +7,7 @@ slug: /api-reference/graphql-and-directives/
 import DocsRating from '../../../src/core/DocsRating';
 import {FbInternalOnly, OssOnly} from 'internaldocs-fb-helpers';
 
-Relay uses directives to add additional information to GraphQL documents, which are used by the Relay compiler to generate the appropriate runtime artifacts. These directives only appear in your application code and are removed from requests sent to your GraphQL server.
+Relay uses directives to add additional information to GraphQL documents, which are used by the [Relay compiler](../../guides/compiler/) to generate the appropriate runtime artifacts. These directives only appear in your application code and are removed from requests sent to your GraphQL server.
 
 **Note:** The Relay compiler will maintain any directives supported by your server (such as `@include` or `@skip`) so they remain part of the request to the GraphQL server and won't alter generated runtime artifacts.
 

website-v2/docs/getting-started/installation-and-setup.md

@@ -13,9 +13,7 @@ import {OssOnly, FbInternalOnly} from 'internaldocs-fb-helpers';
 Install React and Relay using `yarn` or `npm`:
 
 ```sh
-
 yarn add react react-dom react-relay
-
 ```
 
 ## Set up Relay with a single config file
@@ -27,15 +25,12 @@ this to provide zero-config setup (e.g. [vscode-apollo-relay](https://github.com
 Install the package:
 
 ```sh
-
 yarn add --dev relay-config
-
 ```
 
 And create the configuration file:
 
 ```javascript
-
 // relay.config.js
 module.exports = {
   // ...
@@ -44,29 +39,24 @@ module.exports = {
   schema: "./data/schema.graphql",
   exclude: ["**/node_modules/**", "**/__mocks__/**", "**/__generated__/**"],
 }
-
 ```
 
 ## Set up babel-plugin-relay
 
 Relay Modern requires a Babel plugin to convert GraphQL to runtime artifacts:
 
 ```sh
-
 yarn add --dev babel-plugin-relay graphql
-
 ```
 
 Add `"relay"` to the list of plugins your `.babelrc` file:
 
 ```javascript
-
 {
   "plugins": [
     "relay"
   ]
 }
-
 ```
 
 Please note that the `"relay"` plugin should run before other plugins or
@@ -76,17 +66,14 @@ Babel's [documentation on this topic](https://babeljs.io/docs/plugins/#pluginpre
 Alternatively, instead of using `babel-plugin-relay`, you can use Relay with [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros). After installing `babel-plugin-macros` and adding it to your Babel config:
 
 ```javascript
-
 const graphql = require('babel-plugin-relay/macro');
-
 ```
 
 If you need to configure `babel-plugin-relay` further (e.g. to enable `compat` mode), you can do so by [specifying the options in a number of ways](https://github.com/kentcdodds/babel-plugin-macros/blob/master/other/docs/user.md#config-experimental).
 
 For example:
 
 ```javascript
-
 // babel-plugin-macros.config.js
 module.exports = {
   // ...
@@ -95,56 +82,45 @@ module.exports = {
     compat: true,
   },
 }
-
 ```
 
 ## Set up relay-compiler
 
-Relay's ahead-of-time compilation requires the [Relay Compiler](../../guided-tour/setup/compiler/), which you can install via `yarn` or `npm`:
+Relay's ahead-of-time compilation requires the [Relay Compiler](../../guides/compiler/), which you can install via `yarn` or `npm`:
 
 ```sh
-
 yarn add --dev relay-compiler
-
 ```
 
 This installs the bin script `relay-compiler` in your node_modules folder. It's recommended to run this from a `yarn`/`npm` script by adding a script to your `package.json` file:
 
 ```js
-
 "scripts": {
   "relay": "relay-compiler --src ./src --schema ./schema.graphql"
 }
-
 ```
 
 or if you are using jsx:
 
 ```js
-
 "scripts": {
   "relay": "relay-compiler --src ./src --schema ./schema.graphql --extensions js jsx"
 }
-
 ```
 
 Then, after making edits to your application files, just run the `relay` script to generate new compiled artifacts:
 
 ```sh
-
 yarn run relay
-
 ```
 
 Alternatively, you can pass the `--watch` option to watch for file changes in your source code and automatically re-generate the compiled artifacts (**Note:** Requires [watchman](https://facebook.github.io/watchman) to be installed):
 
 ```sh
-
 yarn run relay --watch
-
 ```
 
-For more details, check out our [Relay Compiler docs](../../guided-tour/setup/compiler/).
+For more details, check out our [Relay Compiler docs](../../guides/compiler/).
 
 ## JavaScript environment requirements
 

website-v2/docs/guided-tour/workflow.md

@@ -0,0 +1,35 @@
+---
+id: workflow
+title: Workflow
+slug: /guided-tour/workflow/
+---
+
+import DocsRating from '../../src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'internaldocs-fb-helpers';
+import FbWorkflow from './fb/FbWorkflow.md';
+
+<FbInternalOnly>
+  <FbWorkflow />
+</FbInternalOnly>
+
+<OssOnly>
+
+Before we can get started writing Relay code, we need to make sure to **[setup the Relay Compiler](../../getting-started/installation-and-setup/#set-up-relay-compiler)**.
+
+The **[Relay Compiler](../../guides/compiler/)** will analyze any `graphql` literals inside your Javascript code, and produce a set of artifacts that are used by Relay at runtime, when the application is running on the browser.
+
+So whenever we're developing Relay components, for example by writing [Fragments](../rendering/fragments/) or [Queries](../rendering/queries/), we will need to run the Relay Compiler:
+
+```sh
+yarn run relay
+```
+
+Or we can run it in watch mode, so the artifacts are re-generated as we update our source code:
+
+```sh
+yarn run relay --watch
+```
+
+</OssOnly>
+
+<DocsRating />

website-v2/docs/guided-tour/setup/compiler.md → website-v2/docs/guides/compiler.md

@@ -1,13 +1,14 @@
 ---
 id: compiler
-title: Compiler
-slug: /guided-tour/setup/compiler/
+title: Relay Compiler
+slug: /guides/compiler/
 ---
 
+import DocsRating from '../../src/core/DocsRating';
 import {FbInternalOnly, OssOnly} from 'internaldocs-fb-helpers';
-import DocsRating from '../../../src/core/DocsRating';
-
-<!-- This file is OSS only -->
+import FbRunningCompiler from './fb/FbRunningCompiler.md';
+import FbGraphQLSchema from './fb/FbGraphQLSchema.md';
+import FbImportingGeneratedDefinitions from './fb/FbImportingGeneratedDefinitions.md';
 
 ## `graphql`
 
@@ -32,11 +33,11 @@ The result of using the `graphql` template tag is a `GraphQLTaggedNode`; a runti
 Note that `graphql` template tags are **never executed at runtime**. Instead, they are compiled ahead of time by the Relay compiler into generated artifacts that live alongside your source code, and which Relay requires to operate at runtime.
 
 
-## Relay Compiler
+## Compiler
 
 Relay uses the Relay Compiler to convert [`graphql`](#graphql) literals into generated files that live alongside your source files.
 
-A query like the following:
+A fragment like the following:
 
 ```javascript
 
@@ -48,15 +49,21 @@ graphql`
 
 ```
 
-Will cause a generated file to appear in `./__generated__/MyComponent.graphql`,
+Will cause a generated file to appear in `./__generated__/MyComponent.graphql.js`,
 with both runtime artifacts (which help to read and write from the Relay Store)
 and [Flow types](https://flow.org/) to help you write type-safe code.
 
 The Relay Compiler is responsible for generating code as part of a build step which can then be referenced at runtime. By building the query ahead of time, the Relay's runtime is not responsible for generating a query string, and various optimizations can be performed on the query that could be too expensive at runtime (for example, fields that are duplicated in the query can be merged during the build step, to improve efficiency of processing the GraphQL response).
 
 ### GraphQL Schema
 
-To use the Relay Compiler, you need either a .graphql or .json GraphQL schema file, describing your GraphQL server's API. Typically these files are local representations of a server source of truth and are not edited directly. For example, we might have a `schema.graphql` like:
+<FbInternalOnly>
+  <FbGraphQLSchema />
+</FbInternalOnly>
+
+<OssOnly>
+
+To use the Relay Compiler, you need either a `.graphql` or `.json` [GraphQL Schema](https://graphql.org/learn/schema/) file, describing your GraphQL server's API. Typically these files are local representations of a server source of truth and are not edited directly. For example, we might have a `schema.graphql` like:
 
 ```graphql
 
@@ -80,7 +87,15 @@ type WordDefinition {
 
 ```
 
-### Source files
+</OssOnly>
+
+### Running the Compiler
+
+<FbInternalOnly>
+  <FbRunningCompiler />
+</FbInternalOnly>
+
+<OssOnly>
 
 Additionally, you need a directory containing `.js` files that use the `graphql` tag to describe GraphQL queries and fragments. Let's call this `./src`.
 
@@ -132,8 +147,18 @@ This would produce three generated files, and two `__generated__` directories:
 -   `src/Components/__generated__/DictionaryComponent_definition.graphql.js`
 -   `src/Queries/__generated__/DictionaryQuery.graphql.js`
 
+</OssOnly>
+
+
 ### Importing generated definitions
 
+<FbInternalOnly>
+  <FbImportingGeneratedDefinitions />
+
+</FbInternalOnly>
+
+<OssOnly>
+
 Typically you will not need to import your generated definitions. The [Relay Babel plugin](../../../getting-started/installation-and-setup#setup-babel-plugin-relay) will then convert the `graphql` literals in your code into `require()` calls for the generated files.
 
 However the Relay Compiler also automatically generates [Flow](https://flow.org) types as [type comments](https://flow.org/en/docs/types/comments/). For example, you can import the generated Flow types like so:
@@ -150,4 +175,7 @@ More rarely, you may need to access a query, mutation, fragment or subscription
 import DictionaryComponent_word from './__generated__/DictionaryComponent_word.graphql';
 ```
 
+</OssOnly>
+
+
 <DocsRating />

website-v2/sidebars.js

@@ -14,13 +14,14 @@ const {fbContent} = require('internaldocs-fb-helpers');
 const Guides = fbContent({
   internal: [
     'guides/graphql-server-specification',
+    'guides/compiler',
     'guides/fb/updating-the-graphql-schema',
     'guides/fb/flow-typing',
-    'guides/client-schema-extensions',
     'guides/fb/writing-subscriptions',
     'guides/testing-relay-components',
     'guides/testing-relay-with-preloaded-components',
     'guides/fb/required-directive',
+    'guides/client-schema-extensions',
     {
       EntryPoints: [
         'guides/fb/entrypoints/entrypoints',
@@ -44,6 +45,7 @@ const Guides = fbContent({
   ],
   external: [
     'guides/graphql-server-specification',
+    'guides/compiler',
     'guides/persisted-queries',
     'guides/network-layer',
     'guides/client-schema-extensions',
@@ -77,13 +79,8 @@ module.exports = {
       ],
       'A Guided Tour': [
         'guided-tour/introduction',
+        'guided-tour/workflow',
         {
-          'Setup and Workflow': [
-            ...fbContent({
-              internal: ['guided-tour/setup/fb/build-script'],
-              external: ['guided-tour/setup/compiler'],
-            }),
-          ],
           'Rendering Data Basics': [
             'guided-tour/rendering/queries',
             'guided-tour/rendering/fragments',