Add support for switching books to asciidoctor (#606)

Adds support for switching individual books to Asciidoctor in `conf.yaml`.
It then cuts the glossary over to Asciidoctor. This is what the changed
docs look like:
https://github.com/elastic/built-docs-nik/commit/dfafa93c3c483bf74c2091f832c916f1ccc842ba

There are some line break changes which we can ignore. There is a change
to the HTML - in a `<dd>` AsciiDoc added a `<p class="simpara">` tag.
Asciidoctor does not. The rendered result looks ever so slightly better
to me so I'm personally fine with it. The font size is `15px` instead of
`16px` and the weight is `400` instead of `normal`.

Author: nik9000

conf.yaml

@@ -81,6 +81,7 @@ contents:
             branches:   [ master ]
             tags:       Elastic Stack/Glossary
             subject:    Elastic Stack
+            asciidoctor: true
             sources:
               -
                 repo:   stack-docs

doc_build_aliases.sh

@@ -41,7 +41,7 @@ alias docbldlsold='$GIT_HOME/docs/build_docs.pl --doc $GIT_HOME/logstash/docs/in
 # Stack
 alias docbldstk='$GIT_HOME/docs/build_docs.pl --doc $GIT_HOME/stack-docs/docs/index.asciidoc'
 
-alias docbldgls='$GIT_HOME/docs/build_docs.pl --doc $GIT_HOME/stack-docs/docs/en/glossary/index.asciidoc'
+alias docbldgls='$GIT_HOME/docs/build_docs --asciidoctor --doc $GIT_HOME/stack-docs/docs/en/glossary/index.asciidoc'
 
 alias docbldgs='$GIT_HOME/docs/build_docs.pl --doc $GIT_HOME/stack-docs/docs/en/getting-started/index.asciidoc --chunk 1'
 

lib/ES/Book.pm

@@ -114,6 +114,21 @@ sub new {
 
     my $lang = $args{lang} || 'en';
 
+    # be careful about true/false here so there are no surprises.
+    # otherwise someone is bound to set `asciidoctor` to `false`
+    # and perl will evaluate that to true....
+    my $asciidoctor = 0;
+    if (exists $args{asciidoctor}) {
+        $asciidoctor = $args{asciidoctor};
+        if ($asciidoctor eq 'true') {
+            $asciidoctor = 1;
+        } elsif ($asciidoctor eq 'false') {
+            $asciidoctor = 0;
+        } else {
+            die 'asciidoctor must be true or false but was ' . $asciidoctor;
+        }
+    }
+
     bless {
         title         => $title,
         dir           => $dir->subdir($prefix),
@@ -132,7 +147,7 @@ sub new {
         private       => $args{private} || '',
         noindex       => $args{noindex} || '',
         lang          => $lang,
-        asciidoctor   => $args{asciidoctor} || 0,
+        asciidoctor   => $asciidoctor,
     }, $class;
 }
 
@@ -153,7 +168,7 @@ sub build {
         $Opts->{procs},
         sub {
             my ( $pid, $error, $branch ) = @_;
-            $self->source->mark_done( $title, $branch );
+            $self->source->mark_done( $title, $branch, $self->asciidoctor );
         }
     );
 
@@ -219,7 +234,7 @@ sub _build_book {
            if -e $branch_dir
         && !$rebuild
         && !$template->md5_changed($branch_dir)
-        && !$source->has_changed( $self->title, $branch );
+        && !$source->has_changed( $self->title, $branch, $self->asciidoctor );
 
     my ( $checkout, $first_path ) = $source->prepare($branch);
 

lib/ES/Repo.pm

@@ -132,7 +132,7 @@ sub _reference_args {
 sub has_changed {
 #===================================
     my $self = shift;
-    my ( $title, $branch, $path ) = @_;
+    my ( $title, $branch, $path, $asciidoctor ) = @_;
 
     my $old
         = $self->tracker->sha_for_branch( $self->name,
@@ -145,6 +145,7 @@ sub has_changed {
         or die "Remote branch <origin/$branch> doesn't exist "
         . "in repo "
         . $self->name;
+    $new .= '|asciidoctor' if $asciidoctor;
 
     return if $old eq $new;
 
@@ -162,11 +163,12 @@ sub has_changed {
 sub mark_done {
 #===================================
     my $self = shift;
-    my ( $title, $branch, $path ) = @_;
+    my ( $title, $branch, $path, $asciidoctor ) = @_;
 
     local $ENV{GIT_DIR} = $self->git_dir;
 
     my $new = sha_for($branch);
+    $new .= '|asciidoctor' if $asciidoctor;
     $self->tracker->set_sha_for_branch( $self->name,
         $self->_tracker_branch(@_), $new );
 
@@ -296,7 +298,9 @@ sub all_repo_branches {
         my $shas = $repo->tracker->shas_for_repo( $repo->name );
 
         for my $branch ( sort keys %$shas ) {
-            my $log = run( qw(git log --oneline -1), $shas->{$branch} );
+            my $sha = $shas->{$branch};
+            $sha =~ s/\|.+$//;  # Strip |asciidoctor if it is in the hash
+            my $log = run( qw(git log --oneline -1), $sha );
             my ($msg) = ( $log =~ /^\w+\s+([^\n]+)/ );
             push @out, sprintf "  %-35s %s   %s", $branch,
                 substr( $shas->{$branch}, 0, 8 ), $msg;

lib/ES/Source.pm

@@ -50,9 +50,10 @@ sub has_changed {
     my $self   = shift;
     my $title  = shift;
     my $branch = shift;
+    my $asciidoctor = shift;
     for my $source ( $self->_sources_for_branch($branch) ) {
         return 1
-            if $source->{repo}->has_changed( $title, $branch, $source->{path} );
+            if $source->{repo}->has_changed( $title, $branch, $source->{path}, $asciidoctor );
     }
     return;
 }
@@ -63,8 +64,9 @@ sub mark_done {
     my $self   = shift;
     my $title  = shift;
     my $branch = shift;
+    my $asciidoctor = shift;
     for my $source ( $self->_sources_for_branch($branch) ) {
-        $source->{repo}->mark_done( $title, $branch, $source->{path} );
+        $source->{repo}->mark_done( $title, $branch, $source->{path}, $asciidoctor );
     }
     return;
 }

lib/ES/Util.pm

@@ -112,7 +112,7 @@ sub build_chunked {
                 file('resources/website_chunked.xsl')->absolute,
                 "$dest/index.xml"
             );
-            # unlink "$dest/index.xml";
+            unlink "$dest/index.xml";
             1;
         } or do { $output = $@; $died = 1; };
     }