Browse files

feat: improved documentation site and release process

  • Loading branch information...
maoo committed Oct 19, 2018
1 parent b322716 commit efad8d8dde2f50e6ef651ac35389ad36f4b681af
@@ -1,3 +1,11 @@
@@ -0,0 +1,48 @@
language: node_js
- 8

# travis encrypt GITHUB_TOKEN=....
# travis encrypt GITHUB_USERNAME=....
# travis encrypt GITHUB_PASSWORD=....
# travis encrypt GH_TOKEN=....
# travis encrypt NPM_TOKEN=...
# - secure: ""

- npm install -g yarn
- yarn install
- yarn test
- yarn run doc

# TODO - enable it when ready to release
# - provider: script
# skip_cleanup: true
# script: npm run semantic-release
# on:
# branch: master
- provider: script
skip_cleanup: true
script: ./
branch: master
- provider: pages
skip-cleanup: true
github-token: $GITHUB_TOKEN
verbose: true
keep-history: true
local-dir: docs
target_branch: gh-pages
branch: master

# TODO - enable it when ready to release
# notifications:
# email:
# -
# -
@@ -1,13 +1,68 @@
# FDC3 API specifications

API Working Group repository.
[![npm version](](
[![Build Status](](

See the [specification draft](/Specification-Draft.MD) for the current working documentation, and the [FDC3 Confluence page]( for further information.
Visit the [documentation website]( for more info.

### Development
## Release
The FDC3 API is released under the [FINOS NPMJS Organisation](

On every commit, [semantic release]( will be executed by Travis CI and - based on the commit message - will decide to trigger a release or not.

Release managers can use [commitizen]( to simplify their commit process; simply install `npm install -g commitizen` and use `git cz` (instead of `git commit`) to commit your changes.

When a release is performed, Travis CI will do the following:
- Run all build and validation tasks defined by [`.travis.yml`](.travis.yml)
- Create a GitHub tag, labelled after the `version` specified in `package.json`
+ Include a `` file with a recap of all commits added since last release
+ Publish (on ``) an updated version of the NPM package defined by `package.json`
- Increase the the `version` specified in `package.json` and push changes to `master` branch

### Release setup
Travis CI must be configured with the following environment variables:
- `GH_TOKEN`, used to create tags on GitHub
- `NPM_TOKEN`, used to publish the npm package

You can setup variables [using semantic-release-cli](, [Travis Repository Settings]( or with the [travis CLI](

Release configurations can also be [shared across npm projects](

### Advanced configurations
Semantic release allows [additional configurations]( to customise the release flow.

## Run locally
To run the website documentation locally, please follow the steps below.

### Install Ruby (MacOS)

It is strongly advised to use RVM or RBenv to install Ruby; below are the steps to install RVM on MacOS.
yarn install
mkdir -p ~/.rvm/src && cd ~/.rvm/src && rm -rf ./rvm && \
git clone --depth 1 && \
cd rvm && ./install
rvm install 2.5.2
which bundle #Should return a .rvm sub-path
which ruby #Should return a .rvm sub-path

When making changes to the TypeScript interfaces, run `yarn test` to ensure there are no syntax errors, and `yarn run doc` to regenerate the documentation.
### Install gems needed for jekyll

cd /tmp
git clone
cd slate
rm -rf .bundle
gem install jekyll-theme-slate
gem install jekyll-seo-tag
gem install jekyll-watch

# Run jekyll on other project
cd ../API/docs
jekyll serve --incremental
@@ -0,0 +1 @@

This file was deleted.

Oops, something went wrong.
@@ -0,0 +1,15 @@
theme: jekyll-theme-slate

title: FDC3 API specifications

version: '[[tag]]'

description: The documentation website for the FINOS FDC3 API specifications

google_analytics: UU-123456

show_downloads: false

is_project_page: true
@@ -0,0 +1,73 @@
<!DOCTYPE html>
<html lang="{{ site.lang | default: "en-US" }}">

<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,maximum-scale=2">
<link rel="stylesheet" type="text/css" media="screen" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
<link rel="stylesheet" href="" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
{% seo %}

<div id="main_content_wrap container" class="outer">
<div class="row">
<div class="col-3 left-column">
<div class="column-menu">
<p class="column-title"><a href="" target="_blank"><img src="" alt="FDC3 logo"/></a></p>
<div class="column-icons">
<a href="" target="_blank">
<img src=";width=48&amp;height=48&amp;name=github-logo.png"/></a>
<a href="" target="_blank">
<img width="25" height="25" style="border:none" src=";height=48&amp;name=atlassian-logo.png"></a>
<a href="" target="_blank">
<img src=";height=48&amp;name=twitter-logo.png"></a>
<ul class="column-menu">
<li><a href="/">Getting Started</a></li>
<li><a href="/ts">API specs</a></li>
<li><a href="/CHANGELOG.html">What's new in {{ site.version }}</a></li>
<li><a href="" target="_blank">FDC3 API Working Group</a>
<li><a href="" target="_blank">FINOS FDC3 Program</a></li>
<div class="column-footer">
<a href="" target="_blank"><img src="" alt="FINOS logo"/></a>
<p>Release: {{ site.version }}</p>
<div class="col-9 main_content">
<section id="main_content" class="inner">
{{ content }}

<!-- FOOTER -->
<!-- <div id="footer_wrap" class="outer">
<footer class="inner">
{% if site.github.is_project_page %}
<p class="copyright">{{ site.title | default: site.github.repository_name }} maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
{% endif %}
<p>Published with <a href="">GitHub Pages</a></p>
</div> -->

{% if site.google_analytics %}
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
ga('create', '{{ site.google_analytics }}', 'auto');
ga('send', 'pageview');
{% endif %}
<script src="" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
<script src="" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
<script src="" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
@@ -0,0 +1,93 @@

html, body {
.outer, .row {

.left-column {
padding-right: 0px !important;
background-color: #322A38 !important;
.main_content {
padding-left: 0px !important;
overflow-x: scroll;

.column-menu {
text-decoration: none;
.column-menu a {
text-decoration: none;
.column-menu a:visited {
text-decoration: none;
.column-menu a:hover {
text-decoration: none;
.column-menu img {
height: 100px;
margin: 0 20px 0 20px;
box-shadow: none !important;

.column-title {
margin-top: 20px;
text-align: center;

.column-icons img {
width: 48px;
height: 48px;
.column-icons {
text-align: center;

ul.column-menu {
padding-left: 0px !important;
padding-top: 20px !important;
margin-left: 40px;
font-size: 18px;
ul.column-menu li {
margin-bottom: 5px;
list-style: none !important;

.column-footer {
background-color: #63b7bf;
text-align: center;
padding-left: 15%;
padding-right: 15%;
padding-top: 5%;
padding-bottom: 5%;
position: absolute;
width: 100%;
bottom: 0;
left: 0;
.column-footer h2 {
color: #ffffff !important;
.column-footer h3 {
background: none !important;
.column-footer img {
height: 100px;
margin: 10px;
box-shadow: none !important;

@import "jekyll-theme-slate";
Oops, something went wrong.

0 comments on commit efad8d8

Please sign in to comment.