API Blueprint to S3
A complete workflow for converting API Blueprint to hosted documentation on S3
tl;dr
Create, build, and deploy your API documentation with a single command:
$ gulp create && gulp build && gulp deploy --env=prod
Installation
Clone the repository:
$ git clone git@github.com:philipbrown/api-blueprint-s3.git && cd api-blueprint-s3
Delete the existing git repository:
$ rm -R .git
Create a new git repository:
$ git init
Install the dependencies from NPM:
$ npm install
Create a config.json
file from the example:
$ cp config.json.example config.json
Writing the source files
For each section of your documentation, create a new file under the source
directory. The create
process will concatenate each section into a single file.
Once you are ready to create your API Blueprint document, run the following command:
$ gulp create
You can also watch
this directory to automatically build the blueprint whenever you make a change and save the document:
$ gulp watch
Building the documentation
Once you are ready to convert your blueprint into HTML documentation, run the following command:
$ gulp build
This process uses aglio to parse the blueprint and render it as HTML. See that repository for full configuration options and details of the available themes.
Deploying to S3
When you are ready to deploy to S3, run the following command:
$ gulp deploy --env=(dev|prod)