SDK

Openware SDK contains the stack documentation website build files and CI helpers scripts, including version bumping and documentation aggregation.

Repo structure

SDK uses middleman paired with redcarpet for website generation. middleman config is located in config.rb. TheDocs theme is used for styling.

source

source folder contains website layouts (source/*.html.erb, source/layouts/, source/partials) and documentation source (source/docs, source/api and source/changelogs).

  • source/docs, source/api and source/changelogs folders content is generated with CI, if you want to update it, edit the coresponding page in component's docs/ folder.
  • source/guides contains handwritten guides and can be edited.

assets

assets folder contains images and TheDocs theme sources (assets/javascripts, assets/stylesheets).

  • Website theme builds with gulp pipelines (gulpfile.js).

lib

lib folder contains middleman rendering helpers (lib/sdk/web) and CI helpers rake tasks (lib/tasks).

Git Branches

  • master - used for SDK development.
  • edge - used for website CI autodeployment, represents the latest alpha version, components' master branches should go here.
  • *-stable - used for website CI autodeployment, stable versions releases, components *-stable branches should go here.

Development

Install Dependencies

Install dependencies: sh bundle install --jobs=$(nproc) npm i

For changelog generation you need also install git-chglog.

Cloning modules

For the list of components visit config/components.yml. You can add/remove components by editing this list. If you want to use a specific tag, specify it:

- name: barong
  url: git@github.com:rubykube/barong.git
  tag: 2.2.8 # default is the latest tag

Make sure you have access to all components and an ssh key configured. If you do not want to use ssh, change components' remote urls to use https.

Then run:

bundle exec rake sdk:clone

Collecting documentation

To collect all modules' documentation, run:

bundle exec rake sdk:collect

Each modules' documentation will be inside source/docs/%module_name% directory.

To generate changelogs:

bundle exec rake sdk:generate

Each modules' changelog will be under source/changelogs/%module_name% directory.

Run documentation website

To run local middleman website:

bundle exec middleman serve

And visit http://localhost:4567

Redeploy

edge, 2-2-stable and 2-3-stable SDK branches are deployed automatically on every push.

Dockerfile-website is used for website packing.

If you want to deploy and mount documetation on specific path, use PATH_PREFIX variable:

PATH_PREFIX=/your/path docker build -f Dockerfile-website .