Skip to content

Latest commit

 

History

History
121 lines (101 loc) · 4.71 KB

README.md

File metadata and controls

121 lines (101 loc) · 4.71 KB
Raw

Docs Toolchain Logo

Github workflow Coverage Status Inline docs PRs Welcome

docs-toolchain

Toolchain for TecDoc managed documentation repositories

Built with Ruby Built with Science forthebadge Uses Badges Approved

Docs and Metrics

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/)
  1. pre:
  • combine Javascript files to BLOB file
  • transpile (cross-browser compatibility and loading speed)
  1. build:
  • invoke asciidoctor (with multipage converter)
  • [future] diagram integration
  • Table of Content injector
  • CodeRay source code highlighter
  1. post:
  • create Table of Content
  • create search index (Lunr)
  1. deploy:
  1. notify:

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