Generate browser guide from AsciiDoc

.editorconfig

@@ -0,0 +1,7 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4

src/main/java/com/neo4j/sandbox/updater/BatchUpdater.java

@@ -14,6 +14,7 @@
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -75,7 +76,9 @@ public void updateBatch() throws IOException {
             Path cloneLocation = cloneLocationsBaseDir.resolve(repositoryName(repositoryUri));
             String branch = null;
             try {
-                List<Path> updatedFiles = updater.updateCodeExamples(settings.getCodeSamplesPath(), cloneLocation, repositoryUri);
+                List<Path> updatedFiles = new ArrayList<>();
+                updatedFiles.addAll(updater.updateCodeExamples(settings.getCodeSamplesPath(), cloneLocation, repositoryUri));
+                updatedFiles.addAll(updater.generateBrowserGuides(cloneLocation, repositoryUri));
                 branch = generateConsistentBranchName(repositoryName(repositoryUri), updatedFiles);
                 createPullRequest(repositoryUri, cloneLocation, branch);
             } catch (BlankCommitException exception) {

src/main/java/com/neo4j/sandbox/updater/BrowserGuideConverter.java

@@ -0,0 +1,31 @@
+package com.neo4j.sandbox.updater;
+
+import org.asciidoctor.Asciidoctor;
+import org.asciidoctor.Options;
+import org.springframework.stereotype.Service;
+
+import java.io.File;
+import java.net.URISyntaxException;
+import java.util.Objects;
+
+@Service
+public class BrowserGuideConverter {
+
+    private final File browserGuideTemplatesDir;
+
+    private final Asciidoctor parser;
+
+    public BrowserGuideConverter(Asciidoctor parser) throws URISyntaxException {
+        this.parser = parser;
+        this.browserGuideTemplatesDir = new File(Objects.requireNonNull(BrowserGuideConverter.class.getResource("/templates/browser-guide")).toURI());
+    }
+
+    public String convert(File asciiDocFile) {
+        Options asciidoctorOptions = Options.builder()
+            .templateDirs(this.browserGuideTemplatesDir)
+            .headerFooter(true)
+            .toFile(false)
+            .build();
+        return parser.convertFile(asciiDocFile, asciidoctorOptions);
+    }
+}

src/main/java/com/neo4j/sandbox/updater/Updater.java

@@ -2,20 +2,18 @@
 
 import com.neo4j.sandbox.git.GitOperations;
 import com.neo4j.sandbox.github.GithubSettings;
-import com.neo4j.sandbox.updater.formatting.DefaultQueryIndenter;
-import com.neo4j.sandbox.updater.formatting.IndentDetector;
-import com.neo4j.sandbox.updater.formatting.JavaQueryIndenter;
-import com.neo4j.sandbox.updater.formatting.QueryIndenter;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.stereotype.Component;
 
+import java.io.File;
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.stream.Collectors;
 
 @Component
 public class Updater {
@@ -26,18 +24,64 @@ public class Updater {
 
     private final TemplateEngine templateEngine;
 
+    private final BrowserGuideConverter browserGuideConverter;
+
     private final GithubSettings githubSettings;
 
 
     public Updater(GitOperations cloner,
                    MetadataReader metadataReader,
+                   BrowserGuideConverter browserGuideConverter,
                    GithubSettings githubSettings) {
 
         this.cloner = cloner;
         this.templateEngine = new TemplateEngine(metadataReader);
+        this.browserGuideConverter = browserGuideConverter;
         this.githubSettings = githubSettings;
     }
 
+    /**
+     * Generates browser guides.
+     * <p>
+     * The updater will clone the repository if {@code cloneLocation} does not denote an existing path.
+     * <p>
+     *
+     * @param cloneLocation path to the local clone of the sandbox repository (will be created by `git clone` if it
+     *                      does not exist)
+     * @param repositoryUri URI of the sandbox repository
+     * @return the list of generated browser guides
+     * @throws IOException if any of the underlying file operations fail
+     */
+    public List<Path> generateBrowserGuides(Path cloneLocation, String repositoryUri) throws IOException {
+        if (cloneLocation.toFile().exists()) {
+            LOGGER.debug("Clone of {} already exists at location {}. Skipping git clone operation.", repositoryUri, cloneLocation);
+        } else {
+            LOGGER.trace("About to clone {} at {}.", repositoryUri, cloneLocation);
+            this.cloner.clone(cloneLocation, repositoryUri, githubSettings.getToken());
+        }
+        Path documentationFolder = cloneLocation.resolve("documentation");
+        if (!documentationFolder.toFile().exists()) {
+            LOGGER.debug("Folder documentation does not exist in repository {}. Skipping.", repositoryUri);
+            return new ArrayList<>();
+        }
+        LOGGER.trace("About to generate browser guide for {}.", repositoryUri);
+        List<Path> asciiDocPaths = Files.list(documentationFolder).filter(path -> {
+            File file = path.toFile();
+            return file.isFile() && file.getName().endsWith(".adoc");
+        }).collect(Collectors.toList());
+        List<Path> generatedFiles = new ArrayList<>(asciiDocPaths.size());
+        for (Path asciiDocPath : asciiDocPaths) {
+            File asciiDocFile = asciiDocPath.toFile();
+            LOGGER.trace("About to convert {} of {} to browser guide.", asciiDocFile, repositoryUri);
+            String content = browserGuideConverter.convert(asciiDocFile);
+            String outputFileName = asciiDocFile.getName().replaceFirst("\\.adoc$", ".neo4j-browser-guide");
+            Path browserGuidePath = documentationFolder.resolve(outputFileName);
+            Files.write(browserGuidePath, content.getBytes(StandardCharsets.UTF_8));
+            generatedFiles.add(browserGuidePath);
+        }
+        return generatedFiles;
+    }
+
     /**
      * Updates every code sample of the provided sandbox repository.
      * <p>

src/main/resources/templates/browser-guide/block_admonition.html.erb

@@ -0,0 +1,21 @@
+<%#encoding:UTF-8%><div<%= @id && %( id="#{@id}") %> class="<%= ['admonitionblock',(attr :name),role].compact * ' ' %>">
+<table>
+<tr>
+<td class="icon"><%
+if @document.attr? :icons, 'font' %>
+<i class="fa icon-<%= attr 'name' %>" title="<%= attr 'textlabel' %>"></i><%
+elsif @document.attr? :icons %>
+<img src="<%= icon_uri(attr :name) %>" alt="<%= attr 'textlabel' %>"><%
+else %>
+<div class="title label"><%= attr 'textlabel' %></div><%
+end %>
+</td>
+<td class="content"><%
+if title? %>
+<div class="title label"><%= title %></div><%
+end %>
+<%= content %>
+</td>
+</tr>
+</table>
+</div>

src/main/resources/templates/browser-guide/block_audio.html.erb

@@ -0,0 +1,13 @@
+<%#encoding:UTF-8%><div<%= @id && %( id="#{@id}") %> class="<%= ['audioblock',@style,role].compact * ' ' %>"><%
+if title? %>
+<div class="title"><%= captioned_title %></div><%
+end %>
+<div class="content">
+<audio src="<%= media_uri(attr :target) %>"<%
+if option? :autoplay %> autoplay<% end
+unless option? :nocontrols %> controls<% end
+if option? :loop %> loop<% end %>>
+Your browser does not support the audio tag.
+</audio>
+</div>
+</div>

src/main/resources/templates/browser-guide/block_colist.html.erb

@@ -0,0 +1,28 @@
+<%#encoding:UTF-8%><div<%= @id && %( id="#{@id}") %> class="<%= ['colist',@style,role].compact * ' ' %>"><%
+if title? %>
+<div class="title"><%= title %></div><%
+end
+if @document.attr? :icons
+  font_icons = @document.attr? :icons, 'font' %>
+<table><%
+  items.each_with_index do |item, i|
+    num = i + 1 %>
+<tr>
+<td><%
+    if font_icons %><i class="conum" data-value="<%= num %>"></i><b><%= num %></b><%
+    else %><img src="<%= icon_uri %(callouts/#{num}) %>" alt="<%= num %>"><%
+    end %></td>
+<td><%= item.text %></td>
+</tr><%
+  end %>
+</table><%
+else %>
+<ol><%
+  items.each do |item| %>
+<li>
+<p><%= item.text %></p>
+</li><%
+  end %>
+</ol><%
+end %>
+</div>

src/main/resources/templates/browser-guide/block_dlist.html.erb

@@ -0,0 +1,87 @@
+<%#encoding:UTF-8%><%
+case @style
+when 'qanda'
+%><div<%= @id && %( id="#{@id}") %> class="<%= ['qlist','qanda',role].compact * ' ' %>"><%
+  if title? %>
+<div class="title"><%= title %></div><%
+  end %>
+<ol><%
+  items.each do |questions, answer| %>
+<li><%
+    [*questions].each do |question| %>
+<p><em><%= question.text %></em></p><%
+    end
+    unless answer.nil?
+      if answer.text? %>
+<p><%= answer.text %></p><%
+      end
+      if answer.blocks? %>
+<%= answer.content %><%
+      end
+    end %>
+</li><%
+  end %>
+</ol>
+</div><%
+when 'horizontal'
+%><div<%= @id && %( id="#{@id}") %> class="<%= ['hdlist',role].compact * ' ' %>"><%
+  if title? %>
+<div class="title"><%= title %></div><%
+  end %>
+<table><%
+  if (attr? :labelwidth) || (attr? :itemwidth) %>
+<colgroup>
+<col<%= (attr? :labelwidth) ? %( style="width: #{(attr :labelwidth).chomp '%'}%;") : nil %>>
+<col<%= (attr? :itemwidth) ? %( style="width: #{(attr :itemwidth).chomp '%'}%;") : nil %>>
+</colgroup><%
+  end
+  items.each do |terms, dd| %>
+<tr>
+<td class="hdlist1<%= (option? :strong) ? ' strong' : nil %>"><%
+    terms = [*terms]
+    last_term = terms.last
+    terms.each do |dt| %>
+<%= dt.text %><%
+      if dt != last_term %>
+<br><%
+      end
+    end %>
+</td>
+<td class="hdlist2"><%
+    unless dd.nil?
+      if dd.text? %>
+<p><%= dd.text %></p><%
+      end
+      if dd.blocks? %>
+<%= dd.content %><%
+      end
+    end %>
+</td>
+</tr><%
+  end %>
+</table>
+</div><%
+else
+%><div<%= @id && %( id="#{@id}") %> class="<%= ['dlist',@style,role].compact * ' ' %>"><%
+  if title? %>
+<div class="title"><%= title %></div><%
+  end %>
+<dl><%
+  items.each do |terms, dd|
+    [*terms].each do |dt| %>
+<dt<%= !@style ? ' class="hdlist1"' : nil %>><%= dt.text %></dt><%
+    end
+    unless dd.nil? %>
+<dd><%
+      if dd.text? %>
+<p><%= dd.text %></p><%
+      end
+      if dd.blocks? %>
+<%= dd.content %><%
+      end %>
+</dd><%
+    end
+  end %>
+</dl>
+</div><%
+end %>

src/main/resources/templates/browser-guide/block_example.html.erb

@@ -0,0 +1,8 @@
+<%#encoding:UTF-8%><div<%= @id && %( id="#{@id}") %> class="<%= ['exampleblock',role].compact * ' ' %>"><%
+if title? %>
+<div class="title"><%= captioned_title %></div><%
+end %>
+<div class="content">
+<%= content %>
+</div>
+</div>

src/main/resources/templates/browser-guide/block_floating_title.html.erb

@@ -0,0 +1 @@
+<%#encoding:UTF-8%><%= %(<h#{@level + 1}#{@id && %[ id="#{@id}"]} class="#{[@style, role].compact * ' '}">#{title}</h#{@level + 1}>) %>

src/main/resources/templates/browser-guide/block_image.html.erb

@@ -0,0 +1,15 @@
+<%#encoding:UTF-8%><div<%= @id && %( id="#{@id}") %> class="<%= ['imageblock',@style,role].compact * ' ' %>"<%
+if (attr? :align) || (attr? :float)
+%> style="<%= [("text-align: #{attr :align};" if attr? :align),("float: #{attr :float};" if attr? :float)].compact * ' ' %>"<%
+end %>>
+<div class="content"><%
+if attr? :link %>
+<a class="image" href="<%= attr :link %>"><img src="<%= image_uri(attr :target) %>" alt="<%= attr :alt %>"<%= (attr? :width) ? %( width="#{attr :width}") : nil %><%= (attr? :height) ? %( height="#{attr :height}") : nil %>></a><%
+else %>
+<img src="<%= image_uri(attr :target) %>" alt="<%= attr :alt %>"<%= (attr? :width) ? %( width="#{attr :width}") : nil %><%= (attr? :height) ? %( height="#{attr :height}") : nil %>><%
+end %>
+</div><%
+if title? %>
+<div class="title"><%= captioned_title %></div><%
+end %>
+</div>

src/main/resources/templates/browser-guide/block_listing.html.erb

@@ -0,0 +1,41 @@
+<%#encoding:UTF-8%><div<%= @id && %( id="#{@id}") %> class="<%= ['listingblock',role].compact * ' ' %>"><%
+if title? %>
+<div class="title"><%= captioned_title %></div><%
+end %>
+<div class="content"><%
+nowrap = !(@document.attr? :prewrap) || (option? :nowrap)
+if @style == 'source'
+  language = attr :language
+  code_class = language ? [language, %(language-#{language})] : []
+  pre_class = ['highlight']
+  pre_lang = language
+  case attr 'source-highlighter'
+  when 'coderay'
+    pre_class = ['CodeRay']
+  when 'pygments'
+    pre_class = ['pygments','highlight']
+  when 'prettify'
+    pre_class = ['prettyprint']
+    pre_class << 'linenums' if attr? :linenums
+    pre_class << language if language
+    pre_class << %(language-#{language}) if language
+    code_class = []
+  when 'html-pipeline'
+    pre_lang = language
+    pre_class = code_class = []
+    nowrap = false
+  end
+  pre_class << "pre-scrollable"
+  pre_class << "programlisting"
+  pre_class << "cm-s-neo"
+  pre_class << "code"
+  pre_class << "runnable"
+  pre_class << "standalone-example"
+  pre_class << "ng-binding" 
+  pre_class << 'nowrap' if nowrap %>
+<pre mode="cypher" <%= pre_class.empty? ? nil : %( class="#{pre_class * ' '}") %><%= pre_lang && %( data-lang="#{pre_lang}") %><%= pre_lang && %( lang="#{pre_lang}") %>><!--code<%= code_class.empty? ? nil : %( class="#{code_class * ' '}") %>--><%= content %><!--/code--></pre><%
+else %>
+<pre<%= nowrap ? ' class="nowrap"' : nil %>><%= content %></pre><%
+end %>
+</div>
+</div>

src/main/resources/templates/browser-guide/block_literal.html.erb

@@ -0,0 +1,8 @@
+<%#encoding:UTF-8%><div<%= @id && %( id="#{@id}") %> class="<%= ['literalblock',role].compact * ' ' %>"><%
+if title? %>
+<div class="title"><%= title %></div><%
+end %>
+<div class="content">
+<pre<%= !(@document.attr? :prewrap) || (option? :nowrap) ? ' class="nowrap"' : nil %>><%= content %></pre>
+</div>
+</div>

src/main/resources/templates/browser-guide/block_math.html.erb

@@ -0,0 +1,17 @@
+<%#encoding:UTF-8%><div<%= @id && %( id="#{@id}") %> class="<%= ['mathblock',role].compact * ' ' %>"><%
+if title? %>
+<div class="title"><%= title %></div><%
+end %>
+<div class="content"><%
+open, close = Asciidoctor::BLOCK_MATH_DELIMITERS[@style.to_sym]
+equation = content.strip
+if (@subs.nil? || @subs.empty?) && !(attr? 'subs')
+  equation = sub_specialcharacters equation
+end
+unless (equation.start_with? open) && (equation.end_with? close)
+  equation = %(#{open}#{equation}#{close})
+end
+%>
+<%= %(#{equation}\n) %>
+</div>
+</div>