Add source_branch attribute

The `source_branch` attribute should be useful in resolving inter-book
links. We can get this *perfect* when we're running with `--all` because
every book already *has* a branch attribute. When we build with `--doc`
we have to guess. I've added some heuristics that I feal are likely to
guess right most of the time for most folks. I'm not too worried about
guessing wrong *sometimes* because, for the most part, that'll only
break interbook links and lots of folks don't check those locally
anyway. And because we have the pull request tests which run with
`--all` so they'll serve as an accurate backstop.

Relates to elastic#804

build_docs.pl

@@ -188,10 +188,34 @@ sub _guess_edit_url {
             $remote = 'unknown';
         }
     }
-    my $branch = eval {run qw(git rev-parse --abbrev-ref HEAD) } || 'master';
+    my $branch = eval { run qw(git rev-parse --abbrev-ref HEAD) } || 'master';
+    $Opts->{branch} = _guess_branch( $branch ) unless $Opts->{branch};
     return ES::Repo::edit_url_for_url_and_branch($remote, $branch);
 }
 
+#===================================
+sub _guess_branch {
+#===================================
+    my $real_branch = shift;
+
+    # Detects common branch patterns like:
+    # 7.x
+    # 7.1
+    # 18.5
+    # Also normalizes brackport style patters like:
+    # blah_blah_7.x
+    # bort_foo_7_x
+    # zip_zop_12.8
+    # qux_12_8
+    return $1 if $real_branch =~ /(\d+[\._][\dx]+)$/;
+
+    # Otherwise we just assume we're trageting master. This'll be right when
+    # the branch is actually 'master' and when this is a feature branch. It
+    # obviously won't always be right, but for the most part that *should* be
+    # ok because we have pull request builds which will double check the links.
+    return 'master';
+}
+
 #===================================
 sub build_local_pdf {
 #===================================

integtest/spec/all_books_spec.rb

@@ -282,6 +282,37 @@ def self.override_edit_me(respect)
       end
     end
   end
+  context 'for a book that uses {source_branch}' do
+    convert_all_before_context do |src|
+      repo = src.repo_with_index 'repo', <<~ASCIIDOC
+        The branch is {source_branch}.
+      ASCIIDOC
+      repo.switch_to_new_branch 'foo'
+      repo.switch_to_new_branch '7.x'
+      repo.switch_to_new_branch '1.2'
+
+      book = src.book 'Test'
+      book.source repo, 'index.asciidoc'
+      book.branches.push 'foo', '7.x', '1.2'
+    end
+    shared_examples 'contains branch' do |branch|
+      it 'contains the branch name' do
+        expect(body).to include("The branch is #{branch}.")
+      end
+    end
+    page_context 'html/test/master/chapter.html' do
+      include_examples 'contains branch', 'master'
+    end
+    page_context 'html/test/foo/chapter.html' do
+      include_examples 'contains branch', 'foo'
+    end
+    page_context 'html/test/7.x/chapter.html' do
+      include_examples 'contains branch', '7.x'
+    end
+    page_context 'html/test/1.2/chapter.html' do
+      include_examples 'contains branch', '1.2'
+    end
+  end
 
   context 'when one source is private' do
     convert_all_before_context do |src|

integtest/spec/single_book_spec.rb

@@ -465,6 +465,61 @@ def self.index
     include_examples 'README-like console alternatives', '.'
   end
 
+  context 'for a book that uses {source_branch}' do
+    INDEX = <<~ASCIIDOC
+      = Title
+
+      [[chapter]]
+      == Chapter
+      The branch is {source_branch}.
+    ASCIIDOC
+    def self.convert_with_source_branch_before_context(branch)
+      convert_single_before_context do |src|
+        unless branch == 'master'
+          src.write 'dummy', 'needed so git is ok with switching branches'
+          src.commit 'dummy'
+          src.switch_to_new_branch branch
+        end
+        src.write 'index.asciidoc', INDEX
+      end
+    end
+    shared_examples 'contains branch' do |branch|
+      page_context 'chapter.html' do
+        it 'contains the branch name' do
+          expect(body).to include("The branch is #{branch}.")
+        end
+      end
+    end
+    context 'when the branch is master' do
+      convert_with_source_branch_before_context 'master'
+      include_examples 'contains branch', 'master'
+    end
+    context 'when the branch is 7.x' do
+      convert_with_source_branch_before_context '7.x'
+      include_examples 'contains branch', '7.x'
+    end
+    context 'when the branch is 1.5' do
+      convert_with_source_branch_before_context '1.5'
+      include_examples 'contains branch', '1.5'
+    end
+    context 'when the branch is 18.5' do
+      convert_with_source_branch_before_context '18.5'
+      include_examples 'contains branch', '18.5'
+    end
+    context 'when the branch is some_crazy_thing' do
+      convert_with_source_branch_before_context 'some_crazy_thing'
+      include_examples 'contains branch', 'master'
+    end
+    context 'when the branch is some_crazy_thing_7.x' do
+      convert_with_source_branch_before_context 'some_crazy_thing_7.x'
+      include_examples 'contains branch', '7.x'
+    end
+    context 'when the branch is some_crazy_thing_7_x' do
+      convert_with_source_branch_before_context 'some_crazy_thing_7_x'
+      include_examples 'contains branch', '7_x'
+    end
+  end
+
   context 'when run with --open' do
     include_context 'source and dest'
     before(:context) do

lib/ES/Book.pm

@@ -290,6 +290,7 @@ sub _build_book {
                 latest        => $latest,
                 respect_edit_url_overrides => $self->{respect_edit_url_overrides},
                 alternatives  => $alternatives,
+                branch => $branch,
             );
         }
         else {
@@ -314,6 +315,7 @@ sub _build_book {
                 latest        => $latest,
                 respect_edit_url_overrides => $self->{respect_edit_url_overrides},
                 alternatives  => $alternatives,
+                branch => $branch,
             );
         }
         $checkout->rmtree;

lib/ES/Toc.pm

@@ -42,6 +42,7 @@ sub write {
             root_dir    => '',  # Required but thrown on the floor with asciidoctor
             latest      => 1,   # Run all of our warnings
             private     => 1,   # Don't generate edit me urls
+            branch => '' # TOCs don't have a branch but it is a required arg
     );
     $adoc_file->remove;
 }

lib/ES/Util.pm

@@ -53,6 +53,7 @@ sub build_chunked {
     my $respect_edit_url_overrides = $opts{respect_edit_url_overrides} || '';
     my $alternatives = $opts{alternatives} || [];
     my $alternatives_summary = $dest->file('alternatives_summary.json');
+    my $branch = $opts{branch};
 
     die "Can't find index [$index]" unless -f $index;
 
@@ -100,6 +101,7 @@ sub build_chunked {
                 '-d' => 'book',
                 '-a' => 'showcomments=1',
                 '-a' => "lang=$lang",
+                '-a' => "source_branch=$branch",
                 # Use ` to delimit monospaced literals because our docs
                 # expect that
                 '-a' => 'compat-mode=legacy',
@@ -147,6 +149,7 @@ sub build_chunked {
                 '-f' => 'chunked',
                 '-a' => 'showcomments=1',
                 '-a' => "lang=$lang",
+                '-a' => "source_branch=$branch",
                 '-a' => 'base_edit_url=' . $edit_url,
                 '-a' => 'root_dir=' . $root_dir,
                 # Use ` to delimit monospaced literals because our docs
@@ -212,6 +215,7 @@ sub build_single {
     my $respect_edit_url_overrides = $opts{respect_edit_url_overrides} || '';
     my $alternatives = $opts{alternatives} || [];
     my $alternatives_summary = $dest->file('alternatives_summary.json');
+    my $branch = $opts{branch};
 
     die "Can't find index [$index]" unless -f $index;
 
@@ -266,6 +270,7 @@ sub build_single {
                 '-d' => $type,
                 '-a' => 'showcomments=1',
                 '-a' => "lang=$lang",
+                '-a' => "source_branch=$branch",
                 $private || !$edit_urls ? () : ( '-a' => "edit_urls=" .
                     edit_urls_for_asciidoctor($edit_urls) ),
                 '-a' => 'asciidoc-dir=' . $asciidoc_dir,
@@ -310,6 +315,7 @@ sub build_single {
                 '-d' => $type,
                 '-a' => 'showcomments=1',
                 '-a' => "lang=$lang",
+                '-a' => "source_branch=$branch",
                 '-a' => 'base_edit_url=' . $edit_url,
                 '-a' => 'root_dir=' . $root_dir,
                 $private ? ( '-a' => 'edit_url!' ) : (),