Good enough documentation with SparrowCI

Often Raku modules authors would start a documentation with something like this:

use MyCoolStuff;

# this module exposes a function named `func` 
# and this function does so and so

my $a = func("a","b","c");

Minimal module documentation usually has a code example of how to use a module and run some basic stuff … The problem is however that sometimes this code example is erroneous, outdated or just does not work … Well, good-doc plugin deals with it!

Good enough documentation

I’ve recently added an experimental plugin to address valid documentation examples issue, it does exactly what is supposed to:

• Parse module’s README.md file
• Extract the very first code snippet (Raku code)
• And, finally execute it

Any case any errors occur during the last step, a warning message is printed out and an entire build is marked as having some warnings:

Pipeline example

Following is an example of how to use the good-doc plugin within a SparrowCI pipeline:

tasks:
  -
    name: test
    default: true
    language: Bash
    code: |
      cd source/
      zef install . --/test
      zef test .
    followup:
      -
        name: good-doc
  -
    name: good-doc
    plugin: good-doc
    config:
      path: source/README.md

Conclusion

As usually I’d like to hear comments if such an experimental feature will be useful for users?

— -

Thanks !