docs-toolchain

Toolchain for TecDoc managed documentation repositories

Docs and Metrics

• Source Code Documentation (rdoc)
• SimpleCov Coverage
• RubyCritic

Quickstart

Dependencies

To run the toolchain locally, or run the unit tests, the following requirements must be met:

• Ruby 2.x
• installed dependencies (Gemfile)

In order to install dependencies, run the following at the root of the project:

bundle install --jobs 4 --retry 3
bundle exec rake -T

NOTE: Use bundle exec rake to invoke rake.

Build

Building the content can be done one stage after another:

rake docs:clean
rake docs:test
rake docs:pre
rake docs:build
rake docs:post

or by using the target all, which runs all of the stages mentioned above:

rake docs:all

Alternatively, use the Docker image at wirecard/docs-dockerfile.

Stages

The toolchain is designed to run through different stages, that have specific responsibilities:

1. setup: install required dependencies
2. test:

• validate all configuration files
• test the current commit with:
  • predefined tests by the toolchain (lib/extensions.d/)
    • ID Checker
    • if Checker
    • Link Checker
    • Pattern Checker
  • custom tests (${CUSTOM_DIR}/extensions.d/)

3. pre:

• combine Javascript files to BLOB file
• transpile (cross-browser compatibility and loading speed)

4. build:

• invoke asciidoctor (with multipage converter)
• [future] diagram integration
• Table of Content injector
• CodeRay source code highlighter

5. post:

• create Table of Content
• create search index (Lunr)

6. deploy:

• wirecard/s3-deploy
• crazy-max/ghaction-github-pages
• required variables, see Configuration/Secret/AWS

7. notify:

• send Slack message stating the fail status and a description if the build failed, see Configuration/Secret/Slack

Development

Rake targets

Toolchain

• rake toolchain:lint calls rubocop
• rake toolchain:test runs unit tests with simplecov and writes report to coverage/index.html
• rake toolchain:quality runs rubycritic and generates an overview in /tmp/rubycritic/overview.html
• rake toolchain:rdoc generates rdoc documentation in /tmp/rdoc
• rake toolchain:inch:grade or rake toolchain:inch:suggest runs inch on the code base

Content (Stages)

1. No rake task: bundle install --jobs 4 --retry 3
2. rake docs:test
3. rake docs:pre
4. rake docs:build
5. rake docs:post
6. No rake task: Deployed by Github Action

Additional tasks

• rake docs:clean: delete build directory and clean up
• rake docs:all: run the stages clean test pre build post
• rake docs:list:<stage>: list loaded extensions for a processing stage
  • rake docs:list:pre
  • rake docs:list:post

Environment Variables

• SKIP_COMBINE: skips the Javascript combine and transpile operation.
• SKIP_HTMLCHECK: skips the HTML Check Post process.
• Skip entire stages
  • SKIP_RAKE_TEST: skips test stage (i.e. rake docs:test)
• FAST sets the following variables (which may be set individually):
  • SKIP_COMBINE, SKIP_HTMLCHECK, SKIP_RAKE_TEST
• DEBUG for debug builds
• SKIP_COMBINE
• additional debug output