Permalink
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 @@
*.js
.vscode
node_modules
node_modules
package-lock.json
docs/ts
.bundle/
docs/.sass-cache/
docs/_site/
.DS_Store
docs/.jekyll-metadata
yarn.lock
@@ -0,0 +1,48 @@
language: node_js
node_js:
- 8

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

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

deploy:
# 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: ./prepare-docs-release.sh
on:
branch: master
- provider: pages
skip-cleanup: true
github-token: $GITHUB_TOKEN
email: $GITHUB_EMAIL
name: $GITHUB_USERNAME
verbose: true
keep-history: true
local-dir: docs
target_branch: gh-pages
on:
branch: master

# TODO - enable it when ready to release
# notifications:
# email:
# - fdc3-api@finos.org
# - announce@finos.org
@@ -1,13 +1,68 @@
# API
# FDC3 API specifications

API Working Group repository.
[![npm version](https://badge.fury.io/js/yarn.svg)](https://badge.fury.io/js/yarn)
[![Build Status](https://travis-ci.org/fdc3/API.svg?branch=master)](https://travis-ci.org/fdc3/API)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

See the [specification draft](/Specification-Draft.MD) for the current working documentation, and the [FDC3 Confluence page](https://finosfoundation.atlassian.net/wiki/spaces/FDC3) for further information.
Visit the [documentation website](https://fdc3-api.finos.org) for more info.

### Development
## Release
The FDC3 API is released under the [FINOS NPMJS Organisation](npmjs.com/org/finos).

On every commit, [semantic release](https://semantic-release.gitbook.io/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](http://commitizen.github.io/cz-cli/) to simplify their commit process; simply install `npm install -g commitizen` and use `git cz` (instead of `git commit`) to commit your changes.
![Commitizen](https://github.com/commitizen/cz-cli/raw/master/meta/screenshots/add-commit.png)

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 `CHANGELOG.md` file with a recap of all commits added since last release
+ Publish (on `npmjs.org/org/finos`) 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](https://semantic-release.gitbook.io/semantic-release/usage/ci-configuration#automatic-setup-with-semantic-release-cli), [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis CLI](https://github.com/travis-ci/travis.rb#env).

Release configurations can also be [shared across npm projects](https://semantic-release.gitbook.io/semantic-release/usage/shareable-configurations).

### Advanced configurations
Semantic release allows [additional configurations](https://semantic-release.gitbook.io/semantic-release/usage/plugins) 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 https://github.com/rvm/rvm.git && \
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 https://github.com/pages-themes/slate
cd slate
rm -rf .bundle
./script/bootstrap
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 @@
fdc3-api.finos.org

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

github:
is_project_page: true
repository_url: https://github.com/fdc3/api
@@ -0,0 +1,73 @@
<!DOCTYPE html>
<html lang="{{ site.lang | default: "en-US" }}">

<head>
<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="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
{% seo %}
</head>

<body>
<!-- MAIN CONTENT -->
<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="finos.org/fdc3" target="_blank"><img src="https://www.finos.org/hs-fs/hubfs/FINOS/website/pages/programs/fdc3-logo.png" alt="FDC3 logo"/></a></p>
<div class="column-icons">
<a href="https://github.com/fdc3/api" target="_blank">
<img src="https://www.finos.org/hs-fs/hubfs/FINOS/website/logos/social-logos/github-logo-black.png?t=1539813516681&amp;width=48&amp;height=48&amp;name=github-logo.png"/></a>
<a href="https://finosfoundation.atlassian.net/wiki/spaces/FDC3/pages/92963924/API+Working+Group" target="_blank">
<img width="25" height="25" style="border:none" src="https://www.finos.org/hs-fs/hubfs/sofin%20assets/External%20logos/atlassian-logo.png?width=48&amp;height=48&amp;name=atlassian-logo.png"></a>
<a href="https://twitter.com/hashtag/fdc3" target="_blank">
<img src="https://www.finos.org/hs-fs/hubfs/sofin%20assets/External%20logos/twitter-logo.png?width=48&amp;height=48&amp;name=twitter-logo.png"></a>
</div>
<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="https://finosfoundation.atlassian.net/wiki/spaces/FDC3/pages/92963924/API+Working+Group" target="_blank">FDC3 API Working Group</a>
<li><a href="https://finos.org/fdc3" target="_blank">FINOS FDC3 Program</a></li>
</ul>
</div>
<div class="column-footer">
<a href="finos.org" target="_blank"><img src="https://www.finos.org/hs-fs/hubfs/sofin%20assets/SOFIN%20LOGOS/FINOS_Icon_Wordmark_White.png" alt="FINOS logo"/></a>
<p>Release: {{ site.version }}</p>
</div>
</div>
<div class="col-9 main_content">
<section id="main_content" class="inner">
{{ content }}
</section>
</div>
</div>
</div>

<!-- 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="https://pages.github.com">GitHub Pages</a></p>
</footer>
</div> -->

{% if site.google_analytics %}
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', '{{ site.google_analytics }}', 'auto');
ga('send', 'pageview');
</script>
{% endif %}
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
</body>
</html>
@@ -0,0 +1,93 @@
---
---

html, body {
width:100%;
height:100%;
margin:0;
}
.outer, .row {
height:100%;
}

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

.column-menu {
color:grey;
text-decoration: none;
}
.column-menu a {
color:grey;
text-decoration: none;
}
.column-menu a:visited {
color:grey;
text-decoration: none;
}
.column-menu a:hover {
text-decoration: none;
color:ligh-grey;
}
.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%;
color:white;
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.