Internal: Add option to build docs/ into theme folder

CONTRIBUTING.md

@@ -10,11 +10,11 @@ Below you'll find information on how to setup a local development environment an
 
 In **[our Wiki](https://github.com/CMSgov/design-system/wiki)** you can find additional information like:
 
-- Pattern proposal process
-- Coding guidelines
-- Guiding principles
-- How to write documentation
-- etc.
+* Pattern proposal process
+* Coding guidelines
+* Guiding principles
+* How to write documentation
+* etc.
 
 ## Running locally
 
@@ -25,7 +25,7 @@ This project uses [Yarn](https://yarnpkg.com/) for package management. Yarn help
 ### Getting started
 
 1. `yarn install`
-   - This will also run [Lerna](https://lernajs.io/) `bootstrap` which allows us to have multiple packages within the same repo (a monorepo). Lerna installs all our dependencies and symlinks any cross-dependencies.
+   * This will also run [Lerna](https://lernajs.io/) `bootstrap` which allows us to have multiple packages within the same repo (a monorepo). Lerna installs all our dependencies and symlinks any cross-dependencies.
 1. `yarn start`
 
 _Note_: When you create a Git commit, any staged scripts will be automatically ran through ESLint and Prettier. If the linter catches an error, your commit will fail. This is a feature, not a bug :)
@@ -34,43 +34,47 @@ _Note_: When you create a Git commit, any staged scripts will be automatically r
 
 These scripts can all be run from the root level of the repo:
 
-- `yarn start`
-  - Starts local server running the documentation site
-  - Regenerates documentation when files change
-- `yarn build`
-  - Compile/transpile/uglify everything and makes things release-ready.
-- `yarn bump`
-  - Increments package versions. Read "[Versioning](https://github.com/CMSgov/design-system/wiki/Versioning)" for more info.
-- `yarn generate`
-  - Generates the necessary files for a new core component
-  - Alias: `yarn g`
-- `yarn test`
-  - Runs JS unit tests
-  - Lints JS using ESLint
-  - Lints Sass using stylelint
-- `yarn test:watch`
-  - Runs JS unit tests and will continue to run tests as files change
-- `yarn update-snapshots`
-  - Updates [Jest snapshots](http://facebook.github.io/jest/docs/en/snapshot-testing.html)
-- `yarn lint`
-  - Runs just the linting portion of the tests
+* `yarn start`
+  * Starts local server running the documentation site
+  * Regenerates documentation when files change
+* `yarn build`
+  * Compile/transpile/uglify everything and makes things release-ready.
+* `yarn bump`
+  * Increments package versions. Read "[Versioning](https://github.com/CMSgov/design-system/wiki/Versioning)" for more info.
+* `yarn generate`
+  * Generates the necessary files for a new core component
+  * Alias: `yarn g`
+* `yarn test`
+  * Runs JS unit tests
+  * Lints JS using ESLint
+  * Lints Sass using stylelint
+* `yarn test:watch`
+  * Runs JS unit tests and will continue to run tests as files change
+* `yarn update-snapshots`
+  * Updates [Jest snapshots](http://facebook.github.io/jest/docs/en/snapshot-testing.html)
+* `yarn lint`
+  * Runs just the linting portion of the tests
 
 #### Theme scripts
 
 You can also use the following scripts to [preview and build a theme](https://github.com/CMSgov/design-system/wiki/site-packages-and-themes):
 
-- `yarn start:theme`
-- `yarn build:theme`
+* `yarn start:theme`
+* `yarn build:theme`
 
-If you have multiple directories inside of `packages/themes`, you can specify which theme to use by passing the scripts the name of the folder. For example: `yarn start:theme -- my-theme-folder-name`
+These scripts will also place the documentation into a `docs` subdirectory in your theme's directory.
+
+If you have multiple directories inside of `packages/themes`, you can specify which theme to use by passing the scripts the name of the folder. For example: `yarn start:theme my-theme-folder-name`
+
+If your documentation site will be uploaded to a subdirectory (ie. example.com/design-system), you can set its root path by passing the `--root` option. For example: `yarn build:theme --root design-system`
 
 ## Submitting a pull request
 
 Here are a few guidelines to follow when submitting a pull request:
 
-- Branch off of `master`: `git checkout -b username/branch-name`
-- Commit your changes
-- Make a pull request against the `master` branch
+* Branch off of `master`: `git checkout -b username/branch-name`
+* Commit your changes
+* Make a pull request against the `master` branch
 
 ## Licenses and attribution
 

lerna.json

@@ -9,9 +9,7 @@
       ]
     }
   },
-  "packages": [
-    "packages/*",
-    "packages/themes/*"
-  ],
+  "npmClient": "yarn",
+  "packages": ["packages/*", "packages/themes/*"],
   "version": "1.9.0"
 }

package.json

@@ -1,27 +1,31 @@
 {
   "name": "design-system",
   "private": true,
-  "description": "A shared set of design and code elements for creating accessible and consistent websites",
+  "description":
+    "A shared set of design and code elements for creating accessible and consistent websites",
   "repository": "CMSgov/design-system",
   "scripts": {
     "build": "NODE_ENV=production gulp build --env=production",
-    "build:theme": "npm run build -- --theme",
+    "build:theme": "yarn build --theme",
     "bump": "lerna publish --skip-git --skip-npm",
     "generate": "yo cmsgov",
     "g": "yarn generate",
     "precommit": "lint-staged",
-    "postinstall": "lerna bootstrap --npm-client=yarn",
-    "posttest": "npm run lint",
+    "postinstall": "lerna bootstrap",
+    "posttest": "yarn lint",
     "start": "NODE_ENV=development gulp watch --env=development",
-    "start:theme": "npm run start -- --theme",
+    "start:theme": "yarn start --theme",
     "test": "jest",
     "test:watch": "NODE_ENV=test jest --watch",
     "update-snapshots": "NODE_ENV=test jest -u",
-    "lint": "eslint tools/ examples/**/src/ packages/**/src/ --ext .js --ext .jsx -f table && gulp lint --env=test --theme"
+    "lint":
+      "eslint tools/ examples/**/src/ packages/**/src/ --ext .js --ext .jsx -f table && gulp lint --env=test --theme"
   },
   "devDependencies": {
-    "@cmsgov/eslint-config-design-system": "file:./packages/eslint-config-design-system",
-    "@cmsgov/stylelint-config-design-system": "file:./packages/stylelint-config-design-system",
+    "@cmsgov/eslint-config-design-system":
+      "file:./packages/eslint-config-design-system",
+    "@cmsgov/stylelint-config-design-system":
+      "file:./packages/stylelint-config-design-system",
     "autoprefixer": "^7.2.3",
     "babel-core": "^6.26.0",
     "babel-jest": "^22.0.3",
@@ -102,9 +106,7 @@
       "<rootDir>/tools/jest/polyfills.js",
       "<rootDir>/tools/jest/setupEnzyme.js"
     ],
-    "snapshotSerializers": [
-      "enzyme-to-json/serializer"
-    ],
+    "snapshotSerializers": ["enzyme-to-json/serializer"],
     "testPathIgnorePatterns": [
       "<rootDir>/examples/",
       "<rootDir>/node_modules/",
@@ -114,11 +116,7 @@
     ]
   },
   "lint-staged": {
-    "*.{js,jsx}": [
-      "prettier --write",
-      "eslint --fix",
-      "git add"
-    ]
+    "*.{js,jsx}": ["prettier --write", "eslint --fix", "git add"]
   },
   "resolutions": {
     "gulp-sass/node-sass": ">=4.7.2"

packages/docs/webpack.config.js

@@ -5,12 +5,13 @@ const path = require('path');
 const webpack = require('webpack');
 
 /**
+ * @param {String} docsPath
  * @param {String} rootPath - Root docs site path
  * @param {Array} packages - Design system and theme package directory names
  * @param {Boolean} hotReload - Enable Webpack's hot module replacement
  * @return {Object} Webpack config
  */
-function createConfig(rootPath = '', packages, hotReload = true) {
+function createConfig(docsPath, rootPath = '', packages, hotReload = true) {
   const packagePaths = packages.map(dir =>
     fs.realpathSync(path.resolve(__dirname, '..', dir, 'src'))
   );
@@ -24,7 +25,7 @@ function createConfig(rootPath = '', packages, hotReload = true) {
     output: {
       path: path.resolve(
         __dirname,
-        `../../${buildPath(rootPath, '/public/scripts/')}`
+        `../../${buildPath(docsPath, rootPath, '/public/scripts/')}`
       ),
       publicPath: path.join('/', rootPath, '/public/scripts/'),
       filename: '[name].js'

tools/gulp/build.js

@@ -19,7 +19,9 @@ module.exports = (gulp, shared) => {
   gulp.task('build:gh-pages', () => {
     if (shared.rootPath !== '') {
       dutil.logMessage('🤝 ', 'Moving files to root of docs directory');
-      return gulp.src(`docs/${shared.rootPath}/**/*`).pipe(gulp.dest('docs'));
+      return gulp
+        .src(`${shared.docsPath}/${shared.rootPath}/**/*`)
+        .pipe(gulp.dest(shared.docsPath));
     }
   });
 

tools/gulp/common/buildPath.js

@@ -1,10 +1,9 @@
 const path = require('path');
 
-/*
-The documentation can be setup to be published in a subdirectory named after the
-package version. This is a simple helper method for outputing the proper build path.
-*/
-
-module.exports = (rootPath, basename = '') => {
-  return path.join('docs', rootPath, basename);
+/**
+ * The documentation can be setup to be published in a subdirectory. This is
+ * a simple helper method for outputting the proper build path.
+ */
+module.exports = (docsPath, rootPath, basename = '') => {
+  return path.join(docsPath, rootPath, basename);
 };

tools/gulp/docs/generateDocPage.js

@@ -7,7 +7,7 @@ const savePage = require('./savePage');
  * Create an HTML page with the documentation's UI
  * @return {Promise}
  */
-function generateDocPage(routes, page, rootPath) {
+function generateDocPage(routes, page, docsPath, rootPath) {
   const componentRenderer = () => {
     if (process.env.NODE_ENV === 'development') {
       // In development mode we let the client handle all of the React rendering,
@@ -24,9 +24,7 @@ function generateDocPage(routes, page, rootPath) {
   }
 
   const head = `${seo(page, rootPath)}
-  <link rel="shortcut icon" type="image/x-icon" href="/${
-    rootPath
-  }public/images/favicon.ico" />
+  <link rel="shortcut icon" type="image/x-icon" href="/${rootPath}public/images/favicon.ico" />
   <link href="https://fonts.googleapis.com/css?family=Roboto+Mono:400,700" rel="stylesheet" />
   <link rel="stylesheet" href="/${rootPath}public/styles/docs.css" />
   ${analytics()}`;
@@ -39,11 +37,14 @@ function generateDocPage(routes, page, rootPath) {
 </script>
 <script src="/${rootPath}public/scripts/index.js"></script>`;
 
-  return savePage({
-    uri: page.referenceURI,
-    head: head,
-    body: body
-  });
+  return savePage(
+    {
+      uri: page.referenceURI,
+      head: head,
+      body: body
+    },
+    docsPath
+  );
 }
 
 /**

tools/gulp/docs/generateHtmlExample.js

@@ -7,10 +7,11 @@ const savePage = require('./savePage');
  * This can then be viewed in a browser, or rendered in an iFrame in
  * the documentation.
  * @param {Object} page
+ * @param {String} docsPath
  * @param {String} rootPath - Root docs site path
  * @return {Promise}
  */
-function generateHtmlExample(page, modifier, rootPath) {
+function generateHtmlExample(page, modifier, docsPath, rootPath) {
   if (rootPath) rootPath = `${rootPath}/`;
   // ie. components.button
   let id = page.reference;
@@ -21,15 +22,16 @@ function generateHtmlExample(page, modifier, rootPath) {
   <link rel="stylesheet" href="/${rootPath}public/styles/example.css" />`;
 
   const body = `${processMarkup(page.markup, modifier)}
-  <script type="text/javascript" src="/${
-    rootPath
-  }public/scripts/example.js"></script>`;
+  <script type="text/javascript" src="/${rootPath}public/scripts/example.js"></script>`;
 
-  return savePage({
-    uri: `${rootPath}example/${id}`,
-    head: head,
-    body: body
-  });
+  return savePage(
+    {
+      uri: `${rootPath}example/${id}`,
+      head: head,
+      body: body
+    },
+    docsPath
+  );
 }
 
 module.exports = generateHtmlExample;

tools/gulp/docs/generatePage.js

@@ -11,33 +11,34 @@ const generateReactExample = require('./generateReactExample');
  * Create an HTML page
  * @param {Array} routes - The documentation's nested routes
  * @param {Object} page
+ * @param {String} docsPath
  * @param {String} rootPath - Root docs site path
  * @param {Boolean} isExample - Whether this page should have the docs UI or
  *   if it only render the markup/reactComponent/reactExample
  * @return {Promise<Boolean>}
  */
-function generatePage(routes, page, rootPath, isExample) {
+function generatePage(routes, page, docsPath, rootPath, isExample) {
   if (isExample) {
-    return generateExamples(page, rootPath);
+    return generateExamples(page, docsPath, rootPath);
   } else if (typeof page.referenceURI === 'string') {
-    return generateDocPage(routes, page, rootPath);
+    return generateDocPage(routes, page, docsPath, rootPath);
   }
 
   return Promise.resolve(false);
 }
 
-function generateExamples(page, rootPath) {
-  return generateHtmlExample(page, null, rootPath)
+function generateExamples(page, docsPath, rootPath) {
+  return generateHtmlExample(page, null, docsPath, rootPath)
     .then(() => {
       if (page.modifiers) {
         return page.modifiers.map(modifier =>
-          generateHtmlExample(page, modifier, rootPath)
+          generateHtmlExample(page, modifier, docsPath, rootPath)
         );
       }
     })
     .then(() => {
       if (page.reactExamplePath) {
-        generateReactExample(page, rootPath);
+        generateReactExample(page, docsPath, rootPath);
       }
     });
 }

tools/gulp/docs/generateReactExample.js

@@ -8,10 +8,11 @@ const webpack = require('webpack');
  * This can then be viewed in a browser, or rendered in an iFrame in
  * the documentation.
  * @param {Object} page
+ * @param {String} docsPath
  * @param {String} rootPath - Root docs site path
  * @return {Promise}
  */
-function generateReactExample(page, rootPath) {
+function generateReactExample(page, docsPath, rootPath) {
   return new Promise((resolve, reject) => {
     if (rootPath) {
       rootPath = `${rootPath}/`;
@@ -38,11 +39,14 @@ function generateReactExample(page, rootPath) {
       <script type="text/javascript" src="/${rootPath}public/scripts/example.js"></script>
       <script type="text/javascript">${exampleScripts}</script>`;
 
-      const output = savePage({
-        uri: `${rootPath}example/${page.reference}`,
-        head: head,
-        body: body
-      });
+      const output = savePage(
+        {
+          uri: `${rootPath}example/${page.reference}`,
+          head: head,
+          body: body
+        },
+        docsPath
+      );
       resolve(output);
     });
   });