This document collection represents the on-going effort to document the Raku programming language with the goals of being comprehensive, easy to use, easy to navigate, and useful to both newcomers and experienced Raku programmers.

An HTML version of the documentation is located online at https://docs.raku.org.

The official source for this documentation is located at raku/doc on GitHub.

This particular document is a quick overview of the process described in more detail in CONTRIBUTING on GitHub. This document also provides a short introduction to writing Raku Pod files, which can be rendered into HTML and other formats.

Structure §

All of the documentation is written in Raku Pod and kept in the doc/ directory, and the doc/Language/ and doc/Type/ subdirectories. These files are processed as collections of definitions or "documentables", which are then post-processed and linked together.

Generating HTML from Pod §

To generate HTML from the Pod files, you'll need:

A recent version of the Rakudo Raku compiler
The Raku modules Pod::To::HTML, Pod::To::BigPage, and URI::Escape which all can be installed via zef. For instance, zef install Pod::To::HTML to install Pod::To::HTML.
Documentable, the document API.
Optional: GraphViz, for creating graphs of the relationships between Raku types.
Optional: Atom Highlights and language-perl6, for syntax highlighting.

To generate the documentation into the html/ folder, run:

documentable start -a -v --highlight

To host the documentation from a web server, have Perl and Mojolicious::Lite installed; if you have Perl, run

cpanm --installdeps .

and then run:

perl app.pl daemon

Contributing §

The documentation is written in Raku Pod.

For a quick introduction to Raku Pod, see Raku Pod.

For full details about the Raku Pod specification, see Synopsis 26, Documentation.

Adding definitions §

Documentables can be defined using an =headN Pod directive, where N is greater than zero (e.g., =head1, =head2, …).

All of the paragraphs and blocks following that directive, up until the next directive of the same level, will be considered part of the documentable. So, in:

    =head2 My Definition

    Some paragraphs, followed by some code:

    =begin code
    my Code $examples = "amazing";
    =end code

    Mind === blown.

    =head3 Minor details about My Definition

    It's fantastic.

    =head2 And now, for something completely different

    …

The documentable My Definition extends down to the =head2 And now….

Documentables may contain other documentables. Class documentables, for example, often contain the methods the class implements.

Definitions must be in one of the following forms to be recognized as the start of a documentable named, say, þ. First the code in the document source:

=item X<C<How to use the þ infix> | infix,þ> (This a special case, which 
is always considered a definition)
 
=item C<The þ Infix> 
 
=item B<The C<þ> Infix> 
 
=item C<Infix þ> 
 
=item B<Infix C<þ>> 
 
=item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)

Then the results on the rendered page:

How to use the þ infix (This is a special case, which is always considered a definition)
The þ Infix
The þ Infix
Infix þ
Infix þ
trait is cached (A special case for the trait documentables)

These items should now be searchable by using the search field in the HTML docs.

You can add emphasis with bold ( B<> ) or italicized ( I<> ), with or without code formatting ( C<> ). Due to current parser limitations, special steps have to be taken to use X<> with other formatting codes; for example:

=item X<B<foo>|Subroutines,foo> a fancy subroutine

renders like this

foo a fancy subroutine

Notice that text after a pipe ('|') has no formatting. Also note that C<> preserves spaces and treats text as verbatim.