vuepress setup (#18)

merged all versions documents into one docs folde

.github/workflows/deploy.yml

@@ -0,0 +1,22 @@
+name: Deploy to GitHub pages
+on:
+  push:
+    branches: [ master ]
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Setup node
+        uses: actions/setup-node@v1
+        with:
+          node-version: '12.x'
+      - name: Build
+        run: ./build.sh
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@3.6.2
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: docs/.vuepress/dist

.gitignore

@@ -1,9 +1,2 @@
-**/_experiments/in/*
-**/_experiments/out/*
-_experiments
-.vscode/*
-*.vscode
-.DS_Store
-*.DS_Store
-*.iml
-*.vscode
+node_modules
+docs/.vuepress/dist

LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright 2019 Open Banking Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,40 +1,59 @@
-# Open Banking Read-Write API Version 3.1.7
+# Read Write API Specifications
 
-The Read/Write Data API specification describes a collection of RESTful APIs that enable TPPs to access information and initiate payments for customers, by connecting to ASPSPs – securely, efficiently, and with customer consent.
+Read Write API Specifications project source 
 
-The specification is structured as a series of profiles, resources and data models. The structure is intended to give ASPSPs a suite of functionality to meet their regulatory and commercial requirements. ASPSPs implementing aspects of the specification should select a version of the R/W Data API Profile, compatible functional profiles (such as Accounts and Transactions or Payments) and compatible resources.
+This is using Github pages for public facing website
 
-Details of version compatibility can be found in **profiles** section and specific sub-sections of **resources and data models** section of the specification.
+## Project structure
 
-This specification should be read in conjunction with the Customer Experience Guidelines, Operational Guidelines and Management Information Requirements. Together these form the OBIE standard, which should enable any ASPSP which implements the specification to meet their obligations under both the CMA Order and PSD2/RTS.
+All specification documents are written in markdown and under the folder `docs/`
 
-## Known Issues
+The markdown specification files are used as source to convert into html and then put somewhere public facing. 
+We're using github pages to release documentation to public.
 
-The specification must be read in conjunction with the [Known Issues](https://openbanking.atlassian.net/wiki/spaces/DZ/pages/47546479/Known+Specification+Issues).
+## Development
 
-## Swagger Specification
+### Requirements
 
-The Swagger Specification for R/W APIs can be downloaded from the following GitHub Repository:
+- node
+- yarn 
+- vuepress (installed by yarn)
 
-[https://github.com/OpenBankingUK/read-write-api-specs](https://github.com/OpenBankingUK/read-write-api-specs)
+### Setup
 
-## Change Log
+To set up this project:
 
-### Version 3.1.7
-No further changes from Version 3.1.7 - Draft 1
+Clone the repo
 
-### Version 3.1.7 - Draft1
+```sh
+git clone git@github.com:OpenBankingUK/read-write-api-docs-pub.git
+```
 
-- __Decision 225 - Debtor account details following payment initiation__ [View Diff](https://github.com/OpenBankingUK/read-write-api-docs-pub/commit/dfbd08c9e8fa5c160c034778425b8ab33e1c0fc7)
-- __Decion 226 - Optional fields for accounts that have been switched out__ [View Diff](https://github.com/OpenBankingUK/read-write-api-docs-pub/commit/8fe664760839d55ca2127b20a101be95f238a6ee)
-- __Miscelleneous fixes to address Known Issues__ [View Diff](https://github.com/OpenBankingUK/read-write-api-docs-pub/compare/bf6d569ad9ae2f3d792e86d4b78b4267978efca2...c465c79887ceb05db4a8b6f8a75b8c61d0404baa)
-  - OBSD-16647 - Fixed incorrect class name for `CreditorAccount` in `domestic-standing-order-consents`
-  - OBSD-16818 - Corrected the `txn` specification for `events` to replace the reference to `x-fapi-transaction-id` with `x-fapi-interaction-id`
-  - OBSD-16778 - Added description for post endpoints in `file-payments`
-  - OBSD-15322 - Updated the account name field sizes for `parties` so that they are consistent
-  - Add additional examples for message signing
-  - OBSD-17345 - Corrected the description and length of `ReferencePaymentOrderId`
-  - OBSD-17586 - In the Accounts resource, corrected `UK.CASS.NotSwitced` in description to `UK.CASS.NotSwitched`
-  - OBSD-18538 - Inconsistent description of "CreationDate" in payment resources.
-  - OBSD-18590 - Incorrect example for usage of `CountrySubDivision`
-- __Update version numbers__ [View Diff](https://github.com/OpenBankingUK/read-write-api-docs/commit/ab83f6bdd7b9e64a3599ede6f89ffeff70984462)
+Install all node dependencies:
+
+```sh
+yarn install --non-interactive
+```
+
+### Running locally
+
+Run the following command and open your browser at `http://:8080/read-write-api-docs-pub/` to see the generated website.
+
+```sh
+yarn docs:dev
+```
+
+## Building
+
+Running the script `build.sh` will generate all HTML in `docs/.vuepress/dist/` folder. 
+
+```sh
+./build.sh
+```
+
+
+## Deploy
+
+Deployment is achieved using github actions to copy the generated html files into github pages branch, making it live.
+
+Check file [.github/workflows/deploy.yml](.github/workflows/deploy.yml) for details on CI/CD pipeline.

build.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Instructions taken from, https://vuepress.vuejs.org/guide/deploy.html#github-pages, and adjusted to make it more pedantic.
+#
+# Tested against:
+#
+# * `GNU bash, version 4.4.23(1)-release (x86_64-apple-darwin17.5.0)`.
+# * `GNU bash, version 4.4.19(1)-release (x86_64-alpine-linux-musl)`.
+#
+# Example:
+# $ docker run --rm -it -v $(pwd)/scripts/deploy.sh:/usr/bin/deploy alpine sh -c 'apk add --no-cache bash && bash --version && /usr/bin/deploy'
+
+# abort on errors and more error-checking.
+set -euo pipefail
+set -o noclobber  # Avoid overlay files (echo "hi" > foo)
+set -o errexit    # Used to exit upon error, avoiding cascading errors
+set -o pipefail   # Unveils hidden failures
+set -o nounset    # Exposes unset variables
+shopt -s nullglob    # Non-matching globs are removed  ('*.foo' => '')
+shopt -s failglob    # Non-matching globs throw errors
+shopt -s nocaseglob  # Case insensitive globs
+shopt -s dotglob     # Wildcards match dotfiles ("*.sh" => ".foo.sh")
+
+# build
+printf "
+ ______ _  _  _     ______
+(_____ (_)(_)(_)   / _____)
+ _____) )  _  _   ( (____  ____  _____  ____  ___
+|  __  / || || |   \____ \|  _ \| ___ |/ ___)/___)
+| |  \ \ || || |   _____) ) |_| | ____( (___|___ |
+|_|   |_\_____/   (______/|  __/|_____)\____|___/
+                          |_|
+"
+
+printf "%b" "\e[32m" "yarn installing dependencies ..." "\e[0m" "\n"
+yarn install --non-interactive
+
+printf "%b" "\e[32m" "running yarn docs:build ..." "\e[0m" "\n"
+yarn docs:build
+
+# copy files ignored by yarn docs:build
+printf "%b" "\e[32m" "copying extra files ..." "\e[0m" "\n"
+mkdir docs/.vuepress/dist/F/references
+cp docs/v3.1.7/references/* docs/.vuepress/dist/v3.1.7/references/
+
+printf "%b" "\e[32m" "content generated in folder " "\e[31m\e[1m" "'docs/.vuepress/.dist'" "\e[0m\e[32m" ", deploy its content on a public website.\n\e[39m"
+

docs/.vuepress/Caddyfile

@@ -0,0 +1,11 @@
+:8080/mi-docs-pub/, :8080/mi-docs-pub {
+    tls off
+
+    log stdout
+    errors stdout
+
+    gzip
+
+    root .
+    browse
+}

docs/.vuepress/config.js

@@ -0,0 +1,37 @@
+const sidebar = require('./sidebar.js');
+const nav = require('./nav.js');
+const head = require('./head.js');
+const devServer = require('./devServer.js');
+
+module.exports = {
+    base: '/read-write-api-docs-pub/',
+    title: '',
+    description: 'OBIE Read/Write API Standards',
+    head,
+    themeConfig: {
+        sidebar: sidebar,
+        nav,
+        logo: '/assets/img/logo-dark.svg',
+        sidebarDepth: 0,
+        searchMaxSuggestions: 10,
+        smoothScroll: true,
+        lastUpdated: false,
+    },
+    extendMarkdown: (md) => {
+        return md;
+    },
+    devServer,
+    css: {
+        sourceMap: true,
+    },
+    runtimeCompiler: true,
+    evergreen: true,
+    extraWatchFiles: [
+        '.vuepress/devServer.js',
+        '.vuepress/enhanceApp.js',
+        '.vuepress/head.js',
+        '.vuepress/markdown.js',
+        '.vuepress/nav.js',
+        '.vuepress/sidebar.js',
+    ],
+};

docs/.vuepress/devServer.js

@@ -0,0 +1,9 @@
+module.exports = {
+    clientLogLevel: 'debug',
+    compress: true,
+    overlay: {
+        warnings: false,
+        errors: false,
+    },
+    watchContentBase: true,
+};

docs/.vuepress/dist/assets/fonts/FONTS.md

@@ -0,0 +1,14 @@
+# `FONTS`
+
+## Equip
+
+<http://nickthetailor.com/fonts/equip/>.
+
+## Metropolis
+
+The The Metropolis Typeface is available to download at:
+
+* [https://www.fontsquirrel.com/fonts/metropolis](https://www.fontsquirrel.com/fonts/metropolis).
+* [https://github.com/chrismsimpson/Metropolis](https://github.com/chrismsimpson/Metropolis).
+
+I've downloaded [Release 9](https://github.com/chrismsimpson/Metropolis/releases/tag/r9), which is available at [docs/.vuepress/public/assets/fonts/metropolis-r9.zip](docs/.vuepress/public/assets/fonts/metropolis-r9.zip).

docs/.vuepress/dist/manifest.json

@@ -0,0 +1,50 @@
+{
+  "name": "OBIE MI Data Standards",
+  "short_name": "OBIE  MI Data Standards",
+  "icons": [
+    {
+      "src": "/mi-docs-pub/assets/img/icons/favicon.ico",
+      "sizes": "48x48",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "/mi-docs-pub/assets/img/icons/favicon-48x48.ico",
+      "sizes": "48x48",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "/mi-docs-pub/assets/img/icons/favicon-16x16.png",
+      "sizes": "16x16",
+      "type": "image/png"
+    },
+    {
+      "src": "/mi-docs-pub/assets/img/icons/favicon-32x32.png",
+      "sizes": "32x32",
+      "type": "image/png"
+    },
+    {
+      "src": "/mi-docs-pub/assets/img/icons/android-chrome-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/mi-docs-pub/assets/img/icons/android-chrome-256x256.png.png",
+      "sizes": "256x256",
+      "type": "image/png"
+    },
+    {
+      "src": "/mi-docs-pub/assets/img/icons/apple-touch-icon.png",
+      "sizes": "180x180",
+      "type": "image/png"
+    },
+    {
+      "src": "/mi-docs-pub/assets/img/icons/apple-touch-icon-180x180.png",
+      "sizes": "180x180",
+      "type": "image/png"
+    }
+  ],
+  "start_url": "/mi-docs-pub/index.html",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#ffffff"
+}

docs/.vuepress/dist/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow:

docs/.vuepress/enhanceApp.js

@@ -0,0 +1,45 @@
+// https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements
+export default ({
+    Vue, // the version of Vue being used in the VuePress app
+    options, // the options for the root Vue instance
+    router, // the router instance for the app
+    siteData // site metadata
+}) => {
+    // ...apply enhancements to the app
+}
+
+// // // https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements
+// // export default ({
+// //     Vue, // the version of Vue being used in the VuePress app
+// //     options, // the options for the root Vue instance
+// //     router, // the router instance for the app
+// //     siteData // site metadata
+// // }) => {
+// //     // ...apply enhancements to the app
+
+// export default ({ router }) => {
+//     // Redirect everything to v3.1.2 of the specification.
+//     // Taken from https://github.com/vuejs/vuepress/issues/239#issuecomment-384269121.
+//     router.addRoutes([
+//         { path: '/', redirect: '/v3.1.2/specification/mi-reporting-profile.html' },
+//         { path: '/v3.1.2/', redirect: '/v3.1.2/specification/mi-reporting-profile.html' },
+//         { path: '/v3.1.2/specification/', redirect: '/v3.1.2/specification/mi-reporting-profile.html' },
+//     ])
+// }
+
+// // // https://github.com/vuejs/vuepress/issues/239#issuecomment-384269121
+// // export default ({ router }) => {
+// //     router.addRoutes([
+// //       { path: '/', redirect: 'v3.1.2/specification/mi-reporting-profile.html' },
+// //       { path: '/mi-docs-pub', redirect: 'v3.1.2/specification/mi-reporting-profile.html' },
+// //       { path: '/mi-docs-pub/', redirect: 'v3.1.2/specification/mi-reporting-profile.html' },
+// //       { path: '/mi-docs-pub/v3.1.2', redirect: 'v3.1.2/specification/mi-reporting-profile.html' },
+// //       { path: '/mi-docs-pub/v3.1.2/', redirect: 'v3.1.2/specification/mi-reporting-profile.html' },
+// //       { path: '/mi-docs-pub/v3.1.2/specification', redirect: 'v3.1.2/specification/mi-reporting-profile.html' },
+// //       { path: '/mi-docs-pub/v3.1.2/specification/', redirect: 'v3.1.2/specification/mi-reporting-profile.html' },
+// //       { path: '/test1/', redirect: 'v3.1.2/specification/mi-reporting-profile' },
+// //       { path: '/test2/', redirect: 'v3.1.2/specification/mi-reporting-profile.html' },
+// //     ])
+// //   }
+
+// // TODO: Use this, https://v1.vuepress.vuejs.org/guide/assets.html#base-url, instead.

docs/.vuepress/head.js

@@ -0,0 +1,7 @@
+// // https://vuepress.vuejs.org/config/#head
+module.exports = [
+    [
+        ['link', { rel: 'icon', href: '/assets/img/favicon.ico' }],
+        ['link', { rel: 'manifest', href: '/manifest.json' }],
+    ],
+];