Managoat.Docs.GuardrailCase (managoat_docs v0.1.0)

Copy Markdown View Source

The structural gate on an embedded manual, as a case template. A host uses it once, in a test file of its own, and gets every check in Managoat.Docs.Checks as an ExUnit test against its real manual. The test module's body starts with the use and goes on to tests about the manual's content:

use Managoat.Docs.GuardrailCase,
  docs: MyApp.Docs,
  dockerfile: "Dockerfile",
  unhighlightable: ~w(text txt plain plaintext promql)

Options:

  • docs: (required) the module that uses Managoat.Docs;
  • dockerfile: the image's Dockerfile, relative to the docs module's root/0. Without it the two Dockerfile checks are not generated, for a host that ships no image;
  • unhighlightable: fence languages exempt from the baked-parser check. Defaults to the names that ask for no highlighting.

Why a case template and not a shared test file: the checks only mean something against the host's own manual, Dockerfile and language list, and a host wants them in the same file as the tests about its content, under the same mix test path a CI docs job names. The library runs the same template against a fixture manual, so the checks are exercised before any host uses them.

Every test asserts that a check returned no failures and prints the failures as the assertion message. The messages are the documentation of the incident behind each check; read Managoat.Docs.Checks.