make the .yardopts easier to read
WIP document the env vars

They look awful.  :(
docs should not include unit tests
simplified the toplevel keyboard helpers docs [skip ci]

doc changes only