(Not so) Simple

The documentation verification tool to make sure that nothing is considered easy or simple.

Run Simple in your CI process on your documentation to make sure you don't put out any documentation that is condescending or unhelpful to learners. Everywhere that Simple finds any of the problematic words, it may be a perfect case to provide more detailed documentation.

It's like a unit test for your documentation.

Usage

To use simple, run it from the command line providing the directory the documentation files reside in. Example:

To generate the default configuration file, run init:

simple init

Then you can just run it:

simple

or specify a specific directory:

simple -f./docs/

To get a full list of options and flags, run the help command:

simple help

In CI

In CI, it is recommended to run it like so:

simple --no-color --no-progress-bar --report-file=report.junit.xml

This will force a junit report to be generated, for use in your CI reporting system.

Installation

Simple can either be installed as an executable PHAR, or as a composer dependency.

Alternatively, it can be used with docker for CI builds or locally.

Docker:

The docker image is: marisa50/simple.

To run simple on your docs:

docker run --rm --interactive --tty -v "$(pwd):/app" -w="/app" ghcr.io/m50/simple:latest

Phar:

wget -O simple.phar $(curl -s https://api.github.com/repos/m50/simple/releases/latest | jq -aM .assets[0].browser_download_url | tr -d '"')
chmod 755 simple.phar
mv simple.phar /usr/local/bin/simple

Composer

composer global require m50/simple