Merge pull request #1322 from ably/new-toolchain

New toolchain

.circleci/config.yml

@@ -1,11 +1,143 @@
 version: 2.1
 
 orbs:
-  node: circleci/[email protected]
+  node: circleci/[email protected]
+
+parameters:
+  content-update:
+    type: boolean
+    default: false
+
+commands:
+  restore-npm-cache:
+    steps:
+      - restore_cache:
+          name: Restore NPM Package Cache
+          keys:
+            - npm-packages-v2-{{ .Branch }}-{{ checksum "package-lock.json" }}
+            - npm-packages-v2-{{ .Branch }}-
+            - npm-packages-v2-
+
+  save-npm-cache:
+    steps:
+      - save_cache:
+          name: Save NPM Package Cache
+          key: npm-packages-v1-{{ .Branch }}-{{ checksum "package-lock.json" }}
+          paths:
+            - ~/.cache/npm
+
+  npm-install:
+    steps:
+      - run:
+          name: Dependencies
+          command: npm ci --prefer-offline --cache ~/.cache/npm
+
 jobs:
+  install-dependencies:
+    executor:
+      name: node/default
+      tag: 16.15.1
+    resource_class: medium+
+    steps:
+      - checkout
+      - restore-npm-cache
+      - npm-install
+      - persist_to_workspace:
+          root: .
+          paths:
+            - node_modules
+      - save-npm-cache
+
+  test:
+    executor:
+      name: node/default
+      tag: 16.15.1
+    resource_class: medium
+    steps:
+      - checkout
+      - attach_workspace:
+          at: .
+      - run:
+          name: Run linting
+          command: npm run lint
+      - run:
+          name: Install JUnit coverage reporter
+          command: npm install jest-junit
+      - run:
+          name: Run tests
+          command: npm test -- --ci --collectCoverage=true --coverageDirectory=coverage --coverageReporters=html --runInBand --reporters=default --reporters=jest-junit
+          environment:
+            JEST_JUNIT_OUTPUT_DIR: ./reports/junit/
+      - store_test_results:
+          path: ./reports/junit
+      - store_artifacts:
+          path: coverage
   build:
     executor:
       name: node/default
-      tag: 16.1.0
+      tag: 16.15.1
+    resource_class: medium+
     steps:
-      - run: node -v
+      - checkout
+      - attach_workspace:
+          at: .
+      - run:
+          name: Build
+          command: npm run build
+      - run:
+          name: Require redirects file to be generated
+          command: test -f config/nginx-redirects.conf
+      - run:
+          name: Install nginx & erb
+          command: |
+            sudo apt-get update -qq &&
+            sudo apt-get install --no-install-recommends -y nginx ruby
+      - run:
+          name: Test nginx configuration
+          command: |
+            PORT=3000 erb config/nginx.conf.erb > config/nginx.conf &&
+            mkdir -p logs/nginx &&
+            touch logs/nginx/access.log logs/nginx/error.log &&
+            sudo nginx -p . -c config/nginx.conf -t
+      - run:
+          name: Start nginx
+          command: |
+            mkdir -p logs/nginx &&
+            sudo ./bin/start-nginx
+          background: true
+      - run:
+          name: Wait for nginx
+          command: |
+            until $(curl --retry 10 --output /dev/null --silent --head --fail http://localhost:3001/); do
+                printf '.'
+                sleep 1
+            done
+      - run:
+          name: Smoke test quick start redirects
+          command: |
+            status=$(curl --header "x-forwarded-proto: https" \
+                          --silent --output /dev/null -w "%{http_code}" \
+                          http://localhost:3001/docs/quick-start-guide)
+            if [ ${status} -ne 200 ]; then
+              echo "Expect a 200 status code, got ${status}"
+              exit 1
+            fi
+            status=$(curl --header "x-forwarded-proto: https" \
+                          --silent --output /dev/null -w "%{http_code}" \
+                          http://localhost:3001/docs/quick-start-guide/)
+            if [ ${status} -ne 301 ]; then
+              echo "Expect a 301 status code, got ${status}"
+              exit 1
+            fi
+
+workflows:
+  test_branch:
+    unless: << pipeline.parameters.content-update >>
+    jobs:
+      - install-dependencies
+      - test:
+          requires:
+            - install-dependencies
+      - build:
+          requires:
+            - install-dependencies

.env.example

@@ -0,0 +1,9 @@
+GATSBY_DOCS_SIGNED_IN='true'
+GATSBY_DOCS_API_KEYS='true'
+GATSBY_HUBSPOT_TRACKING_ID='123'
+GATSBY_BOOMERANG_ENABLED=
+GATSBY_POSTHOG_API_KEY=
+GATSBY_HEADWAY_ACCOUNT_ID=
+GATSBY_ABLY_MAIN_WEBSITE='https://ably.com'
+GATSBY_ADDSEARCH_API_KEY=
+GATSBY_DOCS_SITE_URL='http://localhost:9000'

.eslintrc.json

@@ -0,0 +1,56 @@
+{
+  "extends": ["eslint:recommended", "plugin:prettier/recommended", "plugin:jest/recommended", "plugin:jest/style"],
+  "plugins": ["jest", "prettier", "react"],
+  "rules": {
+    "react/display-name": "off",
+    "react/prop-types": "off"
+  },
+  "env": {
+    "browser": true,
+    "es6": true,
+    "jest/globals": true,
+    "node": true
+  },
+  "globals": {
+    "mockMatchMedia": true
+  },
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaFeatures": {
+      "jsx": true
+    }
+  },
+  "settings": {
+    "import/resolver": {
+      "alias": [["./src"]]
+    },
+    "react": {
+      "version": "detect"
+    }
+  },
+  "overrides": [
+    // Typescript
+    {
+      "files": ["*.ts", "*.tsx"],
+      "extends": [
+        "plugin:react/recommended",
+        "plugin:react-hooks/recommended",
+        "plugin:@typescript-eslint/eslint-recommended",
+        "plugin:@typescript-eslint/recommended"
+      ],
+      "plugins": ["@typescript-eslint"],
+      "rules": {
+        // disable the rule for all files
+        "@typescript-eslint/explicit-module-boundary-types": "off",
+        "curly": ["error"],
+        "@typescript-eslint/ban-ts-comment": "warn",
+        "jest/expect-expect": [
+          "error",
+          {
+            "assertFunctionNames": ["expect*"]
+          }
+        ]
+      }
+    }
+  ]
+}

.githooks/README.md

@@ -0,0 +1,9 @@
+# Git Hooks
+
+These are recommended git hooks for your project.
+
+You can activate them by running `npm run repo-githooks` and deactivate them by running `npm run no-githooks`.
+
+`npm run repo-githooks` will set your `core.hooksPath` to the correct folder, an example of running this without `npm` might be `git config core.hooksPath .githooks` - but as the specifics may change it might be more convenient to rely on `npm run repo-githooks`.
+
+`npm run no-githooks` can be substituted at any time for `git config --unset core.hooksPath`.

.githooks/post-checkout

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+npm install
+
+exit 0

.githooks/pre-commit

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+npm run lint-staged

.gitignore

@@ -4,7 +4,15 @@ output
 /crash.log
 .sass*
 /config/jsbin_config.yaml
-/package-lock.json
 *.DS_Store
 tags
 spec/examples.txt
+node_modules/
+.cache/
+public
+.env.*
+!.env.example
+graphql-types.ts
+cli
+dist
+config/nginx-redirects.conf

.prettierrc

@@ -0,0 +1,5 @@
+{
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 120
+}

.slugignore

@@ -0,0 +1,8 @@
+/__mocks__
+/.circleci
+/.github
+/app
+/environment-management
+/layouts
+/lib
+/spec

.tool-versions

@@ -1,2 +1,2 @@
 ruby 3.0.0
-nodejs 14.15.4
+nodejs 16.18.1

LEGACY_README.md

@@ -0,0 +1,115 @@
+# Legacy Toolchain: Nanoc Documentation Repository
+
+This repository contains Ably's documentation, which is visible in two locations:
+
+- <https://docs.ably.com>: A static site which always reflects the latest version of the contents of this repository, being deployed automatically when the `main` branch is updated.
+- <https://ably.com/docs>: Our official documentation, which points to a specific version of this repository. Changes in this repo are not automatically reflected in the official docs, but require intervention by the Ably website team.
+
+Docs are authored in [Textile](https://textile-lang.com/) and rendered using the Ruby-based [Nanoc](https://nanoc.ws/) static site generator.
+
+> **Note**: The instructions on this page are intended for general users. If you are a member of Ably staff there is more specific information in the [internal README](README_INTERNAL.md).
+
+## Why is the Ruby section of Docs considered legacy?
+
+While the legacy toolchain continues to run, it is not possible to preview pages as they will appear on the site without also running the website. This requires a lot of tooling to be installed, which is onerous for onboarding new documentation writers & an unreasonable expectation for open source contributors.
+
+While docker is one possible solution, moving to a new toolchain enables us to have finer control over how components display and behave from within the Ably Docs application.
+
+## Quick start
+
+To run the static site locally, perform the following steps:
+
+1. Clone or fork this repo
+1. Run `bundle install` to install the required dependencies
+1. Execute `bundle exec nanoc live -p 4000`
+1. Visit `https://localhost:4000` in your web browser. Any changes you make to the docs should update the static site automatically.
+
+> **Note**: The Ruby version required is shown in the [.ruby-version file](.ruby-version). If you use [ASDF](https://github.com/asdf-vm/asdf) or compatible tooling to manage your Ruby runtime versions, we have included a [`.tool-versions`](.tool-versions) file.
+
+## Contributing to the Docs
+
+We welcome contributions to our documentation. The following resources will help you:
+
+- [Writing Style Guide](writing-style-guide.md)
+- [Documentation Formatting Guide](/content/client-lib-development-guide/documentation-formatting-guide.textile).
+
+To contribute:
+
+1. Make your changes on a local feature branch.
+1. Commit your changes and push your branch.
+1. Create a pull request (PR) that summarizes what changes you are proposing and why.
+1. The pull request will automatically deploy your changes to a review site that is linked to at the bottom of the PR.
+1. The Ably team will review your PR and might suggest changes and improvements that should be made before your PR can be merged. You can make further commits at this stage and the review site will update to reflect them.
+
+## Running with Docker
+
+Execute the following command:
+
+- `docker-compose up`
+
+This starts a web server at <http://localhost:4000>, builds the static site and allows you to view changes live\*.
+
+> **Notes**:
+
+- This has been tested with Docker version 2.10.7. See [Docker installation instructions](https://docs.docker.com/get-docker/).
+- If you are running on Windows you will need to re-run the `docker-compose up` command to see your changes in the static site, unless you are using [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
+
+### Managing updated dependencies
+
+Occasionally, the `Gemfile` or `Gemfile.lock` files might change and this will cause `docker-compose` to fail with an error similar to this:
+
+```
+webserver_1  | The Gemfile built for this container does not match the current Gemfile i.e. they have changed
+webserver_1  | You must rebuild the container with: $ ./docker-run build
+docs_webserver_1 exited with code 2
+```
+
+When this happens, you need to rebuild the containers by running `docker-compose up --build`.
+
+## Running on Heroku
+
+This repo will automatically run on Heroku, but relies on the following [buildpacks](https://github.com/ably-forks/heroku-buildpack-nanoc):
+
+    $ heroku buildpacks
+    === ably-docs Buildpack URLs
+    1. https://github.com/heroku/heroku-buildpack-ruby
+    2. https://github.com/ably-forks/heroku-buildpack-nanoc
+    3. https://github.com/heroku/heroku-buildpack-static
+
+## Redirects
+
+Redirects are implemented using the [nanoc-redirector](https://github.com/gjtorikian/nanoc-redirector) Ruby gem.
+
+To set up a redirect, add the following to the frontmatter of the page that you want to be the _destination_ of the redirect:
+
+```ruby
+redirect_from:
+  - /redirect-from-this-path/
+```
+
+Then, when you access `/redirect-from-this-path/`, you are redirected to the destination page.
+
+> **IMPORTANT:** Do not include the file extension in the `redirect_from` URLs list. For example:
+
+- `general/versions/v0.8/webhooks` ✅ _Correct!_
+- `general/versions/v0.8/webhooks.textile` ❌ _Incorrect!_
+
+### Updating the redirects YAML file
+
+The website uses the [redirects YAML file](data/redirects.yaml) to handle redirects in the documentation. After configuring a redirect, execute one of the following (depending on how you are running the site) to update `redirects.yaml`:
+
+#### Local install
+
+```bash
+$ bundle exec nanoc compile
+```
+
+#### Docker
+
+```shell
+docker-compose up
+```
+
+## Help and contact
+
+If you have any questions or suggestions, please [get in touch](https://ably.com/contact).