Synopsis 26: documentation

Call me Pod

Pod6 is part of the language

Document as|is code

One of many braids

Perl 6 parses comments.

Let's call it POM

This is Pod6

=begin pod
This ordinary paragraph introduces a code block:

    $this = 1 * code('block');
    $which.is_specified(:by<indenting>);
=end pod
	    

This, too

=head3 X<C<string literal>>
C<'scores.txt'> is a I&t;string literal>.

=begin code :preamble<my $file>
my @names = $file.get.words;
=end code
	    

Code is also doc

Docs from code

=begin pod
This is I<apocrypha>
=head1 Lesson 1
Doc is code
=end pod
say $=pod[0].perl;
=output
Pod::Block::Named.new(name => "pod", config => {}, contents => [Pod::Block::Para.new(config => {}, contents => ["This is ", Pod::FormattingCode.new(type => "I", meta => [], config => {}, contents => ["apocrypha"])]), Pod::Heading.new(level => 1, config => {}, contents => [Pod::Block::Para.new(config => {}, contents => ["Lesson 1"])]), Pod::Block::Para.new(config => {}, contents => ["Doc is code"])])

In the beginning, there was code

Ángel Ganivet on decoupling

If we mix a certain amount of wine with a certain amount of water, we call the mixure wine, since we're taking the part for the whole; but if the mixture is spoiled, we don't say: the mixture is spoiled, but the wine has gone sour

Picture: M.Strīķis [CC BY-SA 3.0], via Wikimedia Commons

We need the right amount of documentation along with code

S26 implemented...

January 2012 by tadzik

Mainly in NQP

A few months later...

FAQ: Why don't doc inline in Rakudo?

It's too slow

Ángel Ganivet on reality

... if we believe they tend to come apart, let's not close our eyes to reality, or swim against the current.

Autor: Manuel Compañy – (1903-12-05). "Actualidades". Blanco y Negro (657). ISSN 0006-4572., Volné dílo, Odkaz

Thus start apocrypha

Hidden book, separated from code

perl6/doc evolved organically

Along with Pod6 implementation

perl6/doc

⇒Index/fragment

⇒⇒Aggregate + Typegraph + highlight

⇒⇒⇒Static HTML

Our target

In the repo

Documentation

Tests

Tooling for Pod6 → Static site

p6doc

Sloooow

Several parsing passes

No caching of results

Exhibit B

- at least one function (disambiguation) which take a long time to complete, but whose purpose no one quite remembers, and yet because there are few tests, no one wants to remove.

Richard Hainsworth in pod-cached/design_proposal.md

Tooling specific, undocumented and untested

Exhibit A

Also

Mojolicious for server

No roadmap

No release policy

Drift from source

No specs for site

The present

Google Summer of Code

Antonio → documentable

Joel → p6doc++

Richard Hainsworth's Pod::To::Cached

my Pod::To::Cached $cache .= new(:source<../pods>);
$cache.update-cache;
for $cache.hash-files.kv -> $source-name, $status {
    say "$source-name is $status";
    say $cache.pod($source-name);
}
	    

Compile only once

Documentable registry

 my $registry = Perl6::Documentable::Registry.new( :$cache, :$topdir,
            :dirs(["Language", "Type", "Programs", "Native"]),  :verbose($v)
        );  

# Perl6::Documentable::Registry BUILD →
$!pod-cache = Pod::To::Cached.new( source => $!topdir,  :$!verbose,
              path   => "." ~ $!topdir );
	  

Builds up to p6doc

sub process-type-pod-files(IO::Path @files,
    --> Array[Perl6::Documentable]
) is export {
    my Perl6::Documentable @results;
    for @files.list -> $f {
        my $documentable = Perl6::Documentable::File.new(
          dir => "Type", filename => $f.basename.Str,
          tg => Perl6::TypeGraph.new-from-file,
          pod => load($f).first );
        $documentable.process();
        @results.push($documentable);
    }
    @results
	  }

The new Perl 6 doc stack

Pod::To::Cached ≜ Perl6::Documentable ≜ P6doc

Documenting now

=begin pod :kind("Type") :subkind("class") :category("generic")
=TITLE class Foo
=SUBTITLE Generic class

    class Foo {}

Foo is the class you use when you are talking about a generic class.

=for code
my Foo $foo .=new

=end pod

Processing the documentation

use Perl6::Documentable::Registry;
my $top-dir = "resources/pods/";
my $registry = Perl6::Documentable::Registry.new(
        topdir    => $top-dir,             # doc containing the pod collection
        dirs      => ["Type", "Language"], # dirs to process
        verbose   => True,
        use-cache => True                  # recommended
      );
$registry.compose;
say $registry.lookup("Type",:by<kind>);
  

Future

Maybe a wishlist

Deploy Antonio's and Joel's improvements

Properly working p6doc

All new Perl6::Documentable

Multi-class document support.

Finish S26 implementation

Indexing

P includes

Pod6 grammar

Deployable to GitHub

Decoupling of documentation and tooling

Wishlist: dynamic site using Cro?

Multiple deployment options

More systematic revision