Shortcut to build asciidocs (elastic#13164)

* Shortcut to build asciidocs

The command to build the Kibana docs using the elastic/docs repo can be
easy to forget, so this script is an easy to way to do it right every
time.

* Configurable docs repo location

For folks that clone the elastic docs repo to a different location than
as a sibling of kibana.

CONTRIBUTING.md

@@ -29,6 +29,7 @@ A high level overview of our contributing guidelines.
     - [Running Browser Automation Tests](#running-browser-automation-tests)
       - [Browser Automation Notes](#browser-automation-notes)
   - [Building OS packages](#building-os-packages)
+  - [Writing documentation](#writing-documentation)
 - [Signing the contributor license agreement](#signing-the-contributor-license-agreement)
 - [Submitting a Pull Request](#submitting-a-pull-request)
 - [Code Reviewing](#code-reviewing)
@@ -320,6 +321,21 @@ npm run build -- --rpm
 
 Distributable packages can be found in `target/` after the build completes.
 
+### Writing documentation
+
+Kibana documentation is written in [asciidoc](http://asciidoc.org/) format in
+the `docs/` directory.
+
+To build the docs, you must clone the [elastic/docs](https://github.com/elastic/docs)
+repo as a sibling of your kibana repo. Follow the instructions in that project's
+README for getting the docs tooling set up.
+
+**To build the docs and open them in your browser:**
+
+```bash
+node scripts/docs.js --open
+```
+
 ## Signing the contributor license agreement
 
 Please make sure you have signed the [Contributor License Agreement](http://www.elastic.co/contributor-agreement/). We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once.

scripts/docs.js

@@ -0,0 +1,2 @@
+require('../src/optimize/babel/register');
+require('../src/docs/cli');

src/docs/cli.js

@@ -0,0 +1,26 @@
+import { execFileSync } from 'child_process';
+import { Command } from 'commander';
+
+import {
+  defaultDocsRepoPath,
+  buildDocsScript,
+  buildDocsArgs
+} from './docs_repo';
+
+const cmd = new Command('node scripts/docs');
+cmd
+  .option('--docrepo [path]', 'local path to the docs repo', defaultDocsRepoPath())
+  .option('--open', 'open the docs in the browser', false)
+  .parse(process.argv);
+
+try {
+  execFileSync(buildDocsScript(cmd), buildDocsArgs(cmd));
+} catch (err) {
+  if (err.code === 'ENOENT') {
+    console.error(`elastic/docs repo must be cloned to ${cmd.docrepo}`);
+  } else {
+    console.error(err.stack);
+  }
+
+  process.exit(1);
+}

src/docs/docs_repo.js

@@ -0,0 +1,20 @@
+import { resolve } from 'path';
+
+const kibanaDir = resolve(__dirname, '..', '..');
+
+export function buildDocsScript(cmd) {
+  return resolve(process.cwd(), cmd.docrepo, 'build_docs.pl');
+}
+
+export function buildDocsArgs(cmd) {
+  const docsIndexFile = resolve(kibanaDir, 'docs', 'index.asciidoc');
+  let args = ['--doc', docsIndexFile, '--chunk=1'];
+  if (cmd.open) {
+    args = [...args, '--open'];
+  }
+  return args;
+}
+
+export function defaultDocsRepoPath() {
+  return resolve(kibanaDir, '..', 'docs');
+}