Skip to content

Commit

Permalink
Shortcut to build asciidocs
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
epixa committed Jul 28, 2017
1 parent 5e9a4ec commit a3cca7d
Show file tree
Hide file tree
Showing 3 changed files with 39 additions and 0 deletions.
16 changes: 16 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -362,6 +363,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.
Expand Down
2 changes: 2 additions & 0 deletions scripts/docs.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
require('../src/optimize/babel/register');
require('../src/docs/cli');
21 changes: 21 additions & 0 deletions src/docs/cli.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import { execFileSync } from 'child_process';
import { resolve } from 'path';

const kibanaDir = resolve(__dirname, '..', '..');
const docsIndexFile = resolve(kibanaDir, 'docs', 'index.asciidoc');
const docsToolDir = resolve(kibanaDir, '..', 'docs');
const docsToolCmd = resolve(docsToolDir, 'build_docs.pl');

const args = process.argv.slice(2);

try {
execFileSync(docsToolCmd, ['--doc', docsIndexFile, '--chunk=1', ...args]);
} catch (err) {
if (err.code === 'ENOENT') {
console.error(`elastic/docs repo must be cloned to ${docsToolDir}`);
} else {
console.error(err.stack);
}

process.exit(1);
}

0 comments on commit a3cca7d

Please sign in to comment.