Dev-tooling Usage

Using docopslab-dev tooling with DocOps Lab project codebases

This guide pertains to the docopslab-dev environment. For complete documentation, see the project’s README.

The environment described and provided here is not optimized for DocOps Lab applications used in third-party projects. For your own applications of DocOps Labs products like ReleaseHx and Issuer, see DocOps Box for a full-featured docs-focused workspace, runtime, and production environment.

For full setup instructions, see DocOps Lab Dev-tooling Setup.

For configuration details, see DocOps Lab Dev-tooling Configuration.

This gem mainly supplies rake tasks for performing common development operations across unified configurations and sub-libraries.

Standard Usage

Run all linters

bundle exec rake labdev:lint:all

Auto-fix safe issues

bundle exec rake labdev:heal

Docker Usage

The container runs with a base command of /bin/bash in interactive mode. Any command you pass it will assume you are starting at a normal prompt, with the exception of rake, which will always convert to bundle exec rake.

Other Ruby commands will either need an explicit lab-dev bundle exec or may run without Bundler, like asciidoctor (globally installed for Vale availability) and bundle itself. Non-Ruby commands like vale and shellcheck are immediately available.

First time in a DocOps Lab project

lab-dev rake labdev:sync:all

Regular development workflow

lab-dev rake labdev:sync:all
lab-dev rake labdev:lint:all
lab-dev rake labdev:heal

Irregular commands

lab-dev vale --config .config/vale.ini README.adoc
lab-dev bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals
lab-dev asciidoctor -o tmp/docs.html README.adoc

Interactive shell for debugging

lab-dev

The Docker container persists gems on the host machine in the local .bundle/ path for performance. All tools use the host project’s Gemfile for version consistency.

Make sure container-managed paths are not tracked in Git. Add .config/.vendor/ and .bundle/ to .gitignore.

Override Commands

Most executions of the packaged tools are handled through Rake tasks, but you can always run them directly, especially to pass arguments not built into the tasks.

RuboCop

bundle exec rubocop --config .config/rubocop.yml [options]
bundle exec rubocop --config .config/rubocop.yml --auto-correct-all
bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals

Vale

vale --config=.config/vale.ini [options] [files]
vale --config=.config/vale.ini README.adoc
vale --config=.config/vale.ini --minAlertLevel=error .

HTMLProofer

bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site

More Example Commands

Lint specific Ruby file with specific rule

bundle exec rake 'labdev:lint:ruby[lib/myfile.rb,Style/StringLiterals]'

Lint all AsciiDoc files for a specific Vale rule

bundle exec rake 'labdev:lint:adoc[,DocOpsLab-Authoring.ExNotEg]'

Lint specific shell script

bundle exec rake 'labdev:lint:bash[scripts/docksh]'

Lint specific file with Vale (text mode)

bundle exec rake 'labdev:lint:text[_docs/myfile.adoc]'

Show a specific lint rule profile

bundle exec rake 'labdev:show:rule[vale,RedHat]'

Tasks and Workflow

bundle exec rake --tasks | grep labdev:

To hide the labdev: tasks from the standard rake --tasks output for an integrated project, use:

bundle exec rake --tasks | grep -v labdev:

Typical Workflow

This tool is for working on DocOps Lab projects or possibly unrelated projects that wish to follow our methodology. A typical workflow might look as follows.

Normal development

git add .
git commit -m "Add new feature"

+ This should yield warnings and errors if active linters find issues.

Auto-fix what you can.
```
bundle exec rake labdev:heal
```
Review the changes.
```
git diff
```

Commit the fixes.

git add -A
git commit -m "Auto-fix linting issues"

Handle any remaining manual fixes.
```
bundle exec rake labdev:lint:all
```

Fix remaining issues manually.

git add -A
git commit -m "Fix remaining linting issues"

Try pushing.
```
git push
```
If all blocking issues are cleared, the push should succeed. Otherwise, more cleanup is needed.

Bypass the pre-push gates (usually to test or demo the failure at origin):

git push --no-verify