config.yml

version: 2.1 # Set the CI version.

# We use orbs to provide some common ruby and node tasks and shorten our config.
# Learn more about orbs: https://circleci.com/orbs/
orbs:
  ruby: circleci/ruby@2.4.0
  node: circleci/node@7.1.0
  md-proofer: hubci/md-proofer@0.1.1
  vale: circleci/vale@1.2.0

# This is using the new Scheduled Pipeline feature.
# Right now (10/2021) there is no UI to configure it, so if you need to
# change it's behavior, you'll have to do it manualy:
# https://circleci.atlassian.net/wiki/spaces/CD/pages/6301483319/Schedule+Pipelines+Migration#Other-methods
# See the "GET", "DELETE" or "PATCH" section.
parameters:
  run-schedule:
    type: boolean
    default: false

# Yaml References enable us to DRY out our config by sharing variables across multiple jobs.
# In this case, we are commonly using the "workspaces" feature to share
# build artifacts and files across jobs. For example, we build our Javascript
# persist it to a workspace to be made available when the Jekyll site builds.
references:
  workspace_root: &workspace_root
    /tmp/workspace
  attach_workspace: &attach_workspace
    attach_workspace:
      at: *workspace_root


# Several steps in this config use the same, specialized ruby-caching steps.
# Commands can be used to extract a common set of steps into a reusable-block.
# In this case, whenever you see `- ruby-deps` as a "step" in the config below,
# It is executing a command to restore_cache, install deps if needed, and save_cache.
commands:
  ruby-deps:
    description: "Runs specialized Ruby cache steps."
    parameters:
      dir:
        description: |
          The directory relative to the root of the repo to run bundle for.
          Leave empty for root directory.
        type: string
        default: ""
    steps:
      - restore_cache:
          key: circleci-docs-v1-{{ .Branch }}-<< parameters.dir >>-{{ checksum "Gemfile.lock" }}
      - run:
          name: Install Ruby dependencies
          command:
            |
            if [[ "<< parameters.dir >>" != "" ]]; then
              cd << parameters.dir >>
            fi
            #cmake is needed fo rugged, a gem dependency
            sudo apt-get update && sudo apt-get install -y cmake
            bundle check --path=vendor/bundle || bundle install --path=vendor/bundle --jobs=4 --retry=3
      - save_cache:
          key: circleci-docs-v1-{{ .Branch }}-<< parameters.dir >>-{{ checksum "Gemfile.lock" }}
          paths:
            - "vendor/bundle"
            - "<< parameters.dir >>/vendor/bundle"
  set-jekyll-basename:
    description: Set JEKYLL_BASENAME env var and persist in $BASH_ENV
    steps:
      - run:
          name: Populate JEKYLL_BASENAME env var
          command: |
            if [ ${CIRCLE_BRANCH} = master -o ${CIRCLE_BRANCH} = main -o ${CIRCLE_BRANCH} = /.*-preview/ ]; then
              echo "export JEKYLL_BASENAME=docs" >> $BASH_ENV;
            else
              echo "export JEKYLL_BASENAME=${CIRCLE_BRANCH}" >> $BASH_ENV;
            fi

  trigger-docs-platform-build:
    description: Call API V2 to deploy content to Docs Platform
    steps:
      - run:
          name: Deploy content to Docs Platform
          command: |
            curl --request POST \
            --url https://circleci.com/api/v2/project/gh/circleci/docs-platform/pipeline \
            --header "Circle-Token: $CIRCLECI_API_KEY" \
            --header 'content-type: application/json' \
            --data '{"branch": "main"}'

  trigger-docs-platform-preview-build:
    description: Call API V2 to deploy content to Docs Platform Preview
    steps:
      - run:
          name: Deploy content to Docs Platform Preview
          command: |
            curl --request POST \
            --url https://circleci.com/api/v2/project/gh/circleci/docs-platform/pipeline \
            --header "Circle-Token: $CIRCLECI_API_KEY" \
            --header 'content-type: application/json' \
            --data '{"branch": "preview"}'

# Workflows orchestrate a set of jobs to be run;
# the jobs for this pipeline are # configured below
workflows:

  lint:
    unless:
      or:
        - equal: [ master, << pipeline.git.branch >> ]
        - equal: [ preview, << pipeline.git.branch >> ]
        - << pipeline.parameters.run-schedule >>
    jobs:
      - vale/lint:
          reference_branch: master

  build-deploy:
    when:
      not: << pipeline.parameters.run-schedule >>
    jobs:
      - build_api_docs
      - build:
          requires:
            - build_api_docs
      - reindex-search:
          filters:
            branches:
              only: master
      - deploy:
          requires:
            - build
          filters:
            branches:
              only: master
      - deploy-preview:
          requires:
            - build
          filters:
            branches:
              only: preview


  # We run a nightly build to refresh content and build docs-platform
  # at least once every day. Triggered every day at 08:00 AM on master branch
  nightly-build:
    when: << pipeline.parameters.run-schedule >>
    jobs:
      - trigger-deploy

jobs:

  build_api_docs: # a job to manage building our api documentation and persisting it to the workspace.
    executor:
      name: ruby/default
      tag: '3.1.3-browsers'
    steps:
      - checkout
      - *attach_workspace
      - run:
          name: "Create landing folder for API doc output"
          command: |
            mkdir -p /tmp/workspace/api/v1
            mkdir -p /tmp/workspace/api/v2
      - ruby-deps:
          dir: src-api
      - restore_cache:
          key: circleci-docs-v2-{{ .Branch }}-{{ checksum "src-api/yarn.lock"}}
      - run:
          name: Install Node dependencies
          command: cd src-api; yarn install
      - save_cache:
          key: circleci-docs-v2-{{ .Branch }}-{{ checksum "src-api/yarn.lock"}}
          paths:
            - src-api/node_modules
      - run:
          name: Build API 1.x documentation with Slate
          command: ./scripts/build_api_docs.sh -v1
      - run:
          name: Build API 2.x documentation with Redocly
          command: ./scripts/build_api_docs.sh -v2
      - persist_to_workspace:
          root: *workspace_root
          paths:
            - api

  # The Main "Build" job. It pulls in assets from previous jobs (the built api docs, and javascript)
  # and puts everything in its place for a Jekyll build.
  build:
    executor:
      name: ruby/default
      tag: '3.1.3-browsers'
    resource_class: medium+
    working_directory: ~/circleci-docs
    environment:
      JEKYLL_ENV: production
      JOB_RESULTS_PATH: run-results
    steps:
      - checkout
      - *attach_workspace
      - md-proofer/install:
          version: "0.3.0"
      - run:
          name: "Test Markdown Files"
          command: md-proofer lint jekyll/_cci2/ jekyll/_api/
      - run:
          name: Install dependencies for pronto gem
          command: sudo apt-get install cmake pkg-config
      - ruby-deps
      - node/install-packages:
          pkg-manager: yarn
          cache-version: &npm-cache-version # Gets cache version from project environment variable (E.g v1)
      - run:
          name: Run markdownlint with pronto
          command: bundle exec pronto run -f github_pr -c origin/master
      - run:
          name: Create results directory
          command: mkdir -p $JOB_RESULTS_PATH
      - run:
          name: "Manage Data Files We'll Need"
          command: ./scripts/pull-docker-image-tags.sh
      - run:
          name: Restore Previous Job Assets (Javascript, API docs) to Jekyll directory.
          command: |
            set -exu
            mkdir -p /tmp/workspace/api
            cp -r /tmp/workspace/api/ jekyll/_api/
            # remove unusued /api folder.
            rm -rf jekyll/_api/api
            cp -r /tmp/workspace/api/* jekyll/_api/
      - run: sudo apt-get --yes install nkf
      - set-jekyll-basename
      - run:
          name: Build the Jekyll site
          command: bundle exec rake build
      - run:
          name: Workaround to pass htmlproofer for docs where baseurl (/docs) is hardcoded
          command: |
            if [ ! ${JEKYLL_BASENAME} = "docs" ]; then
              cd jekyll/_site
              ln -s ${JEKYLL_BASENAME} docs
            fi
      ### NOTE: we are ignoring some files in the HTML proofer as it fails on pending translated docs.
      - run:
          name: Test with HTMLproofer
          command: |
            bundle exec rake test
      - run:
          name: compress jekyll output
          command: |
            tar -zcvf circleci-docs.tar.gz jekyll/_site/
      - store_artifacts: # stores the built files of the Jekyll site
          path: circleci-docs.tar.gz
          destination: circleci-docs
      - store_artifacts: # stores build log output.
          path: run-results/
          destination: run-results
      - persist_to_workspace:
          root: ~/circleci-docs/jekyll/
          paths:
            - _site/*

  reindex-search:
    executor:
      name: ruby/default
      tag: '3.1.3-browsers'
    working_directory: ~/circleci-docs
    environment:
      JEKYLL_ENV: production
    steps:
      - checkout
      - *attach_workspace
      - restore_cache:
          key: circleci-docs-{{ .Branch }}-{{ checksum "Gemfile.lock" }}
      - ruby-deps
      - run:
          name: Update Algolia Index
          command: |
            ALGOLIA_API_KEY=$ALGOLIA_PRIVATE_KEY bundle exec jekyll algolia --source jekyll --config jekyll/_config.yml

  deploy:
    docker:
      - image: cibuilds/aws:2.8.13
    steps:
      - attach_workspace:
          at: ./generated-site
      - set-jekyll-basename
      - trigger-docs-platform-build

  deploy-preview:
    docker:
      - image: cibuilds/aws:2.8.13
    steps:
      - attach_workspace:
          at: ./generated-site
      - set-jekyll-basename
      - trigger-docs-platform-preview-build

  trigger-deploy:
    docker:
      - image: cibuilds/aws:2.8.13
    steps:
      - trigger-docs-platform-build