create-docs-template tool (#152)

* create-docs-template

* improved readme

README.md

@@ -132,6 +132,32 @@ The following file tree will be generated:
 └── index.js
 ```
 
+## yarn run create-docs-template
+
+For the following command:
+
+```
+$ yarn run create-docs-template layers Pane Card
+```
+
+The following file tree will be generated:
+
+```
+/src/layers/docs
+├── index.js
+└── /examples/
+ ├── Pane-basic.example
+ └── Card-basic.example
+```
+
+### Manual steps for docs
+
+This `yarn run create-docs-template` script is far from perfect and still requires manual steps. This includes:
+
+* Making sure to use the right examples and write some docs.
+* Configure `docs/utils/getComponent.js`
+* Configure `docs/components/ComponentsSidebar.js`
+
 ## Server Side Rendering
 
 Evergreen bundles 2 CSS-in-JS solutions, from glamor and ui-box. To make it super easy to do server side rendering and hydration, Evergreen exposes a `extractStyles()` function that will do SSR for both at once. You can see how to use it with Next.js in the [ssr-next example app](examples/ssr-next).

package.json

@@ -20,6 +20,7 @@
  "dev": "start-storybook -p 6006",
  "create-package": "./tools/create-package.js",
  "create-package:components": "./tools/create-package-components.js",
+ "create-docs-template": "./tools/create-docs-template.js",
  "build-storybook": "build-storybook -s .storybook/static -o .out",
  "build-commonjs":
  "BABEL_ENV=commonjs babel src --out-dir commonjs --ignore stories,test,docs --source-maps inline",

tools/create-docs-template.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict'
+/**
+ * This script scaffolds a bare bones docs template inside of a package.
+ *
+ * For the following command:
+ *
+ * `yarn run create-docs-template package-name`
+ *
+ * The following file tree will be generated:
+ *
+ * /src/pacakage-name/docs
+ * ├── index.js
+ * └── /examples/
+ * └── {ComponentName}-basic.example
+ *
+ */
+
+const path = require('path')
+const fs = require('fs-extra')
+const task = require('./task')
+const docsIndexTemplate = require('./docs-index-template')
+
+const packageName = process.argv[2]
+
+module.exports = task('create-docs-template', async () => {
+ const componentNames = [...process.argv]
+ componentNames.splice(0, 3)
+
+ console.log('component names:', componentNames)
+
+ if (!packageName) {
+ throw new Error(
+ 'Missing package name argument, use: `yarn run create-docs-template [package-name]`'
+ )
+ }
+
+ const packageDir = path.join('src', packageName)
+ const docsDir = path.join(packageDir, 'docs')
+ const examplesDir = path.join(docsDir, 'examples')
+
+ // Check if directory already exist
+ const docsDirExistsAlready = await fs.pathExists(docsDir)
+
+ if (docsDirExistsAlready) {
+ throw new Error(`Directory already exists: ${docsDir}`)
+ }
+
+ // Create directory
+ await fs.ensureDir(docsDir)
+ await fs.ensureDir(examplesDir)
+
+ await fs.writeFile(
+ path.join(docsDir, 'index.js'),
+ docsIndexTemplate({ packageName, componentNames })
+ )
+
+ await Promise.all(
+ componentNames.map(async name => {
+ return fs.writeFile(
+ path.join(examplesDir, `${name}-basic.example`),
+ `<${name} />`
+ )
+ })
+ )
+})

tools/docs-index-template.js

@@ -0,0 +1,96 @@
+'use strict'
+
+function getRawImports(componentNames) {
+ return componentNames
+ .map(name => {
+ return `import source${name} from '!raw-loader!../src/${name}'`
+ })
+ .join('\n')
+}
+
+function getImports(componentNames) {
+ return componentNames
+ .map(name => {
+ return `import ${name} from '../src/${name}'`
+ })
+ .join('\n')
+}
+
+function getCodeExamples(componentNames) {
+ return componentNames
+ .map(name => {
+ return `import example${name}Basic from './examples/${name}-basic.example'`
+ })
+ .join('\n')
+}
+
+function getComponents(componentNames) {
+ return componentNames.map(
+ name => `
+ {
+ name: '${name}',
+ source: source${name},
+ description: (
+ <p>
+ The <code>${name}</code> component.
+ </p>
+ ),
+ examples: [
+ {
+ title: 'Basic ${name} Example',
+ codeText: example${name}Basic,
+ scope,
+ },
+ ],
+ },
+ `
+ )
+}
+
+module.exports = ({ packageName, componentNames }) => {
+ return `
+import React from 'react'
+import Box from 'ui-box'
+${getImports(componentNames)}
+
+/* eslint-disable import/no-unresolved, import/no-webpack-loader-syntax */
+${getRawImports(componentNames)}
+/* eslint-enable import/no-unresolved, import/no-webpack-loader-syntax */
+
+/**
+ * Code examples
+ */
+${getCodeExamples(componentNames)}
+
+const title = '${packageName}'
+const subTitle = 'A component.'
+
+const designGuidelines = (
+ <div>
+ <p>
+ The <code>${packageName}</code> component.
+ </p>
+ </div>
+)
+
+const appearanceOptions = null
+
+const scope = {
+ Box,
+ ${componentNames.join(',\n ')}
+}
+
+const components = [
+ ${getComponents(componentNames)}
+]
+
+export default {
+ title,
+ subTitle,
+ designGuidelines,
+ appearanceOptions,
+ components,
+}
+
+`.trim()
+}