=begin pod :kind("Type") :subkind("class") :category("exception")

=TITLE class Failure

=SUBTITLE Delayed exception

    class Failure is Nil { }

A C<Failure> is a I<soft> or I<unthrown> L<Exception|/type/Exception>,
usually generated by calling C<&fail>. It acts as a wrapper around an
L<Exception|/type/Exception> object.

=for comment
A lot of more stuff here

=end pod
      

Searchable

Findable

Indexable

Referenceable

We need Documentable

#| Everything documented inherits from this class
class Documentable {

    has Str  $.name;
    has      $.pod  is required("Needs an actual document");
    has Kind $.kind is required("Is essential metadata");
    has      @.subkinds   = [];
    has      @.categories = [];
    

🕮 Literary programming 🕮

Documentation is precompiled

Work by Antonio Gámiz based on Richard Heinsworth's Pod::To::Cached

Register everything

        my $registry = Documentable::Registry.new(
            :$topdir,
            :dirs( $doc-dirs ),
            :$typegraph-file
            :verbose($v)
        );
        $registry.compose; 

Use the cache, Luke

    if ( $!use-cache ) {
        $!pod-cache = init-cache( $!topdir, $!verbose);
        say "Updating cache";
        $!pod-cache.update-cache;
    }
  

Parse, index, repeat

Generate HTML

my %pod-to-render = Documentable::DocPage::Secondary.new.render($!registry, $name, $kind);
        my Str $html = $!wrapper.render( %pod-to-render,
                                         $kind.Str,
                                        );
        return %(
            document => $html,
            url      => %pod-to-render
        )

Generation

Ship it

rsync -avu -e .
    docs.raku.org@xxx.atikon.io:/var/www/docs.raku.org/

With thanks to Roman Baumer and the Atikon people providing this infra

Find out about it

Parse ChangeLogs

 use LWP::Simple;
my $release = @*ARGS[0] // "2019.03";
my $document = LWP::Simple.get("https://raw.githubusercontent.com/rakudo/rakudo/master/docs/announce/$release.md");
my @parts = $document.split("\n  +");
my $additions-removals = @parts[1,2,3].map: "\n# " ~ * ;
$additions-removals ~~  s:g/\s\s\s\+\s/* [ ] /;
$additions-removals ~~
    s:g[ \[(<alnum>+)\] ] =
    "-[$0](https://github.com/rakudo/rakudo/commit/$0)";
    print $additions-removals;

Use the source and context

Blame helps with context

With helpful commit messages

Spec ≠ Rakudo ≠ Implementation

# https://github.com/rakudo/rakudo/issues/2568
{
    is-deeply 3 ~ ( 5 | "18" ), any("35","318"),
      "does a junction survive ~ Junction";
    is-deeply ( 5 | "18" ) ~ 3, any("53","183"),
      "does a junction survive Junction ~";
    is-deeply ( 5 | "18" ) ~ ( 3 | 6), any("53","56","183",186),
      "does a junction survive Junction ~ Junction";
}

Understand what it does

Produce examples

Go viral

my &fail-routine = &fail;
unless &fail-routine.is-implementation-detail {
    say "&fail is not an implementation detail, can expect backward compatibility";
}
sub PRIVATE-CALCULATION is implementation-detail {
	#`(Not safe to rely on this)
}
if &PRIVATE-CALCULATION.is-implementation-detail {
        say "You better not to rely on &PRIVATE-CALCULATION unless you really know what you are doing";
}
    

Looking at the future

More automation

Save boilerplate writing.

The Great Unification of Docs

That's gonna be GUD

Streamline release/deployment