Move documentation website into separate folder

.circleci/config.yml

@@ -26,7 +26,7 @@ references:
 
   cache_keys_docs: &cache_keys_docs
     keys:
-      - cache-docs-v1-{{ .Branch }}-{{ checksum "./tools/x-docs/package.json" }}
+      - cache-docs-v1-{{ .Branch }}-{{ checksum "./web/package.json" }}
 
   #
   # Cache creation
@@ -39,9 +39,9 @@ references:
 
   create_cache_docs: &create_cache_docs
     save_cache:
-      key: cache-docs-v1-{{ .Branch }}-{{ checksum "./tools/x-docs/package.json" }}
+      key: cache-docs-v1-{{ .Branch }}-{{ checksum "./web/package.json" }}
       paths:
-        - ./tools/x-docs/node_modules/
+        - ./web/node_modules/
 
   #
   # Cache restoration
@@ -93,15 +93,13 @@ jobs:
           name: Checkout next-ci-shared-helpers
           command: git clone --depth 1 [email protected]:Financial-Times/next-ci-shared-helpers.git .circleci/shared-helpers
       - *restore_cache_root
-      - *restore_cache_docs
       - run:
           name: Install project dependencies
           command: make install
       - run:
           name: Run the project build task
           command: make build
       - *create_cache_root
-      - *create_cache_docs
       - persist_to_workspace:
           root: *workspace_root
           paths:
@@ -162,6 +160,14 @@ jobs:
       - add_ssh_keys:
           fingerprints:
             - "2b:98:17:21:34:bf:5d:3b:15:a5:82:77:90:11:03:e9"
+      - *restore_cache_docs
+      - run:
+          name: Install documentation website dependencies
+          command: npm run install-docs
+      - *create_cache_docs
+      - run:
+          name: Build documentation website
+          command: npm run build-docs
       - run:
           name: Publish GitHub Pages
           command: ./private/scripts/gh-pages

.eslintignore

@@ -6,4 +6,4 @@
 **/public/**
 **/public-prod/**
 **/blueprints/**
-tools/x-docs/static/**
+web/static/**

docs/get-started/working-with-x-dash.md

@@ -30,11 +30,12 @@ The repository groups related code together in directories. UI components are st
 
 The documentation you're reading right now is generated from a Markdown file stored in the `docs` directory. Other pages to show the packages and components are created dynamically using information inferred from the repository.
 
-This website is stored in the `tools/x-docs` directory and is built using the static site generator [Gatsby](https://gatsbyjs.org). You don't need to learn Gatsby to get started writing documentation!
+This website is stored in the `web` directory and is built using the static site generator [Gatsby](https://gatsbyjs.org). You don't need to learn Gatsby to get started writing documentation!
 
-Once you have [installed] the x-dash project you can run this command from the repository root to build and run the documentation website:
+Once you have [installed] the x-dash project you can run this command from the repository root to install, build, and run the documentation website:
 
 ```sh
+npm run install-docs
 npm run start-docs
 ```
 

package.json

@@ -11,7 +11,9 @@
     "blueprint": "node private/scripts/blueprint.js",
     "start-storybook": "start-storybook -p ${STORYBOOK_PORT:-9001} -s .storybook/static -h local.ft.com",
     "build-storybook": "build-storybook -o dist/storybook -s .storybook/static",
-    "start-docs": "(cd tools/x-docs && npm start)",
+    "install-docs": "(cd web && npm install)",
+    "start-docs": "(cd web && npm start)",
+    "build-docs": "(cd web && npm build)",
     "heroku-postbuild": "make install && npm run build",
     "prepare": "npx snyk protect || npx snyk protect -d || true"
   },

private/scripts/gh-pages

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-TARGET_DIR=tools/x-docs/public/*
+TARGET_DIR=web/public/*
 TARGET_BRANCH=gh-pages
 TEMP_DIR=tmp
 

web/.npmrc

@@ -0,0 +1 @@
+package-lock=false

tools/x-docs/gatsby-config.js → web/gatsby-config.js

@@ -19,14 +19,14 @@ module.exports = {
 			resolve: 'gatsby-source-filesystem',
 			options: {
 				name: 'docs',
-				path: '../../docs'
+				path: '../docs'
 			},
 		},
 		{
 			resolve: 'gatsby-source-filesystem',
 			options: {
 				name: 'components',
-				path: '../../components',
+				path: '../components',
 				// Don't attempt to load any Storybook or source files, as these may
 				// contain syntax and/or features we cannot parse.
 				ignore: [/stories/, /src/]
@@ -36,7 +36,7 @@ module.exports = {
 			resolve: 'gatsby-source-filesystem',
 			options: {
 				name: 'packages',
-				path: '../../packages'
+				path: '../packages'
 			},
 		},
 		// Handles markdown files (creates "MarkdownRemark" nodes)

tools/x-docs/package.json → web/package.json

@@ -10,19 +10,19 @@
   },
   "license": "ISC",
   "devDependencies": {
-    "@financial-times/x-logo": "file:../../packages/x-logo",
+    "@financial-times/x-logo": "file:../packages/x-logo",
     "case": "^1.5.5",
-    "gatsby": "^2.0.11",
-    "gatsby-remark-autolink-headers": "^2.0.6",
+    "gatsby": "^2.9.8",
+    "gatsby-remark-autolink-headers": "^2.0.18",
     "gatsby-remark-external-links": "0.0.4",
-    "gatsby-remark-prismjs": "^3.0.1",
-    "gatsby-source-filesystem": "^2.0.2",
-    "gatsby-transformer-remark": "^2.1.6",
-    "gatsby-transformer-yaml": "^2.1.1",
-    "graphql-type-json": "^0.2.1",
-    "prismjs": "^1.15.0",
-    "react": "^16.4.1",
-    "react-dom": "^16.4.1",
+    "gatsby-remark-prismjs": "^3.2.10",
+    "gatsby-source-filesystem": "^2.0.42",
+    "gatsby-transformer-remark": "^2.4.0",
+    "gatsby-transformer-yaml": "^2.1.12",
+    "graphql-type-json": "^0.3.0",
+    "prismjs": "^1.16.0",
+    "react": "^16.8.6",
+    "react-dom": "^16.8.6",
     "react-helmet": "^5.2.0"
   },
   "browserslist": [

tools/x-docs/plugins/gatsby-transformer-npm-package/on-create-node.js → web/plugins/gatsby-transformer-npm-package/on-create-node.js

@@ -29,27 +29,4 @@ module.exports = ({ node, actions }) => {
 		createNode(npmPackageNode);
 		createParentChildLink({ parent: node, child: npmPackageNode });
 	}
-
-	const storybookFiles = ['stories/index.js', 'storybook/index.js']
-
-	if (node.internal.type === 'File' && storybookFiles.some((filename) => node.absolutePath.endsWith(filename))) {
-		const contents = require(node.absolutePath);
-
-		const storiesNode = {
-			id: `${node.id} >>> Stories`,
-			children: [],
-			parent: node.id,
-			internal: {
-				type: 'Stories'
-			},
-			stories: contents.stories.map((story) => story.title),
-			fileAbsolutePath: node.absolutePath
-		};
-
-		// Append unique node hash
-		storiesNode.internal.contentDigest = hash(JSON.stringify(storiesNode));
-
-		createNode(storiesNode);
-		createParentChildLink({ parent: node, child: storiesNode });
-	}
 };

tools/x-docs/src/lib/create-npm-package-pages.js → web/src/lib/create-npm-package-pages.js

@@ -24,6 +24,15 @@ module.exports = async (actions, graphql) => {
 		throw result.errors;
 	}
 
+	function hasStorybookConfig(relPath) {
+		const locations = ['stories/index.js', 'storybook/index.js', 'storybook/index.jsx'];
+
+		return locations.some((location) => {
+			const filePath = path.join(relPath, location);
+			return fs.existsSync(filePath);
+		});
+	}
+
 	result.data.npmPackages.edges.map(({ node }) => {
 		// Package manifest slug will be /package so remove it
 		const pagePath = path.dirname(node.fields.slug);
@@ -41,7 +50,7 @@ module.exports = async (actions, graphql) => {
 				packageName: node.manifest.name,
 				packageDescription: node.manifest.description,
 				// Flag if Storybook demos are available for this package
-				storybook: fs.existsSync(path.join(relPath, 'stories', 'index.js')),
+				storybook: hasStorybookConfig(relPath),
 				// Associate readme and story nodes via slug
 				packagePath: path.join(pagePath, 'package'),
 				readmePath: path.join(pagePath, 'readme')

web/static/storybook

@@ -0,0 +1 @@
+../../dist/storybook/