aspec_rb 0.0.1

data/lib/extensions/req_refs.rb

@@ -0,0 +1,191 @@
+require 'asciidoctor/extensions'
+require_relative 'utils/scanner'
+
+# test using ruby benchmark
+
+include ::Asciidoctor
+
+# Retrieve $srcdir from config file:
+$srcdir = 'chapters'
+$reqs = []
+$doclinks = []
+
+adoc_files = Dir.glob("#{$srcdir}/**/*.adoc")
+
+# Find a nicer way to initialize some arrays:
+ssincs, ni_includes, includes, doclinksfix, docs, titles, mainchaps, indexincludes, xrefs = Array.new(10) { [] }
+$reqfixes = []
+
+# From the index, create an array of the main chapters
+File.read('index.adoc').each_line do |li|
+  if li[IncludeDirectiveRx]
+    doc = li.match(/(?<=^include::).+?\.adoc(?=\[\])/).to_s
+    doc = doc.sub(/^\{find\}/, '')
+    indexincludes.push(doc) unless doc == 'config'
+  end
+end
+
+adoc_files.sort!
+adoc_files.each do |filename|
+  main = false
+  chapter = Sform.trim(filename).match(/.+?(?=\/)/).to_s
+
+  # Add a switch if the current document is an include within the index.adoc
+  indexincludes.each do |inc|
+    main = true if inc == filename
+  end
+
+  # Create an array of chapters and contained docs
+  docs.push([filename.sub(/^#{$srcdir}\//, ''), chapter])
+
+  # Main iterator to check for requirements, anchors and xrefs line-by-line
+  File.read(filename).each_line do |li|
+    # Match Requirement Blocks "[req,ABC-123,version=n]"
+    if li[/\[\s*req\s*,\s*id\s*=\s*(\w+-?[0-9]+)\s*,.*/]
+      rid = li.chop.match(/id\s*=\s*(\w+-?[0-9]+)/i).captures[0]
+      path = filename.sub(/^#{$srcdir}\//, '')
+      $reqs.push([rid, li.chop, Sform.trim(path), filename, main, chapter])
+
+    # Match block and section titles
+    elsif li[/^(\=+\s+?\S+.+)/]
+      # Keep track of level 1 sections (Document Titles)
+      h1 = true if li[/^=\s+?\S+.+/]
+      title = li.chop.match(/(?!=+\s)(\S+.+?)$/i).captures[0]
+      title.sub!(/\.(?=\w+?)/, '') if title[/\.(?=\w+?)/]
+      title = title.strip
+      titles.push([title, Sform.trim(filename), filename, Sform.underscorify(title).strip, chapter, main, h1])
+
+    # Match for sub includes
+    elsif li[IncludeDirectiveRx]
+      child = li.match(/(?<=^include::).+?\.adoc(?=\[\])/).to_s
+      child = child.sub(/^\{find\}/, '')
+      childpath = "#{filename.sub(/[^\/]+?\.adoc/, '')}#{child}"
+      includes.push([filename, child, childpath])
+
+    end
+  end
+end
+
+# TODO: - remove unused items in array (prefixed with undserscore)
+# For each main include, store
+titles.each do |_anchor, full, _filename, text, chapter, main, h1|
+  next unless main
+  doc = full.gsub(/^#{chapter}\//, '')
+  mainchaps.push([chapter, doc, text, h1])
+end
+
+# H1 title is used by html-chunker.rb to generate
+# a target document name, e.g. for "= Document Title" the generated chapter
+# will have a filename of "_document_title.html", all requirements
+# within this chapter and its includes need to point to this H1
+# NOTE: this will fail if the h1 title is overridden, this is resolved
+# by the next block
+mainchaps.each do |mchapter, doc, link, h1|
+  next unless h1
+  $doclinks.push([doc, link, mchapter])
+end
+
+# For edge cases - slurp the first 10 lines of each top level document and
+# search for an overridden H1 - the previous line will be an anchor
+$doclinks.delete_if do |doc, _link, mchapter|
+  topleveldoc = "#{$srcdir}/#{mchapter}/#{doc}.adoc"
+  lines = File.foreach(topleveldoc).first(10).join
+  next unless lines[/(?x)\[\[.+?\]\]\n=\s{1,}.+$/]
+  overriding_anchor = lines.match(/(?x)\[\[(.+?)\]\]\n=\s{1,}.+$/).captures[0].to_s
+  doclinksfix.push([doc, overriding_anchor, mchapter])
+  true
+end
+
+# TODO: - see if editing the array in-place is better using map!
+$doclinks += doclinksfix
+
+# Create array of non-indexed includes
+adoc_files.each do |filename|
+  includes.each do |parent, child, childpath|
+    next unless childpath == filename
+    ni_includes.push([parent, child, filename])
+  end
+end
+
+# TODO: - see if editing the array in-place is better using map!
+includes += ni_includes
+
+# Edit the array of Requirements to point to the parent document *if* it is included.
+# TODO use a while loop, repeat until no changes made
+3.times do
+  # initialize an array
+  tempreqs = []
+
+  # Loop through all includes, if the requirement is contained in an include,
+  # edit the $reqs array to point to its parent instead
+  includes.each do |parent, _child, childpath|
+    # Delete the child req if matched
+    $reqs.delete_if do |rid, line, path, _filename, main, chapter|
+      next unless Sform.trim(childpath) == Sform.trim(path)
+      tempreqs.push([rid, line, Sform.trim(parent), parent, main, chapter])
+      true
+    end
+  end
+
+  # TODO: - see if editing the array in-place is better using map!
+  $reqs += tempreqs
+  $reqs.uniq!
+end
+
+# Sort in-place by numberic ID
+$reqs.sort_by!(&:first)
+
+# For all requirements, check which chapter they should finally be in with includes catered for
+# match with a main document name - should be a main chapter title
+$reqs.each do |rid, _line, path, _filename, _main, _chapter|
+  $doclinks.each do |_doc, link, chapter|
+    next unless path == "#{chapter}/#{_doc}"
+    $reqfixes.push([rid, link])
+    break
+  end
+end
+
+# RexRx = /(?<=(?<!\\)&lt;&lt;)(Req-\w+-?.+?)(?=&gt;&gt;)/
+RexRx = /(?<=&lt;&lt;)(Req-\w+-?.+?)(?=&gt;&gt;)/
+
+# TODO: consider a more performant way of matching the requirements here
+Extensions.register do
+  inline_macro do
+    named :reqlink
+
+    match RexRx
+    process do |parent, target|
+      id = target.sub(/^Req-/, '')
+      msg = ''
+      fix = ''
+
+      if target[/,/]
+        msg = target.match(/(?<=,).+/).to_s.strip
+        id = target.sub(/^Req-/, '').sub(/,.+/, '')
+        icon = '<i class="fa fa-info-circle" aria-hidden="true"></i>'
+      end
+
+      displaytext = id
+
+      $reqfixes.each do |fixid, file|
+        next unless fixid == id
+        fix = file
+        break
+      end
+
+      tooltip = if msg != ''
+                  "data-toggle=\"tooltip\" data-placement=\"top\" title=\"#{msg}\""
+                else
+                  ''
+                end
+
+      fix = fix.sub(/^_/, '') if fix[/^_/]
+      link = id.sub(/^Req-/, '')
+      uri = "#{fix}.html##{link}"
+      uri = "##{link}" if fix == ''
+      o = "<span class=\"label label-info\" #{tooltip}>"
+      c = '</span>'
+      (create_anchor parent, %(#{o} #{icon} #{displaytext}#{c}), type: :link, target: uri).convert
+    end
+  end
+end

data/lib/extensions/requirement_appendix.rb

@@ -0,0 +1,108 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+exts = "(\.adoc|\.md|\.html)"
+docsdir = 'chapters'
+
+title = nil
+chapter = nil
+doctitle = nil
+incs = []
+inc_reqs = []
+rows = []
+coms = []
+reqs = []
+reqfixes = []
+
+CommentBlockRx = %r(^\/{4,}$)
+CommentLineRx = %r{^//(?=[^/]|$)}
+
+def trim(s)
+  s.gsub!(/chapters\//, '')
+  s.gsub!(/(\.adoc|\.md|\.html)/, '')
+end
+
+adoc_files = Dir.glob('**/*.adoc')
+adoc_files.sort!
+
+adoc_files.each do |f|
+  inc = false
+  commented = false
+  i = 0
+  File.read(f).each_line do |li|
+    i += 1
+    incommentblock ^= true if li[CommentBlockRx]
+    commented = true if li[CommentLineRx]
+
+    if li[/\[\s*req\s*,\s*id\s*=\s*\w+-?[0-9]+\s*,.*/]
+      title.sub!(/^\./, '')
+      req = [li.chop, f, title]
+
+      if commented || incommentblock
+        coms.push(req)
+      elsif inc
+        inc_reqs.push(req)
+      else
+        reqs.push(req)
+      end
+
+    # Collect all includes
+    elsif li[/^include::.+.adoc\[\]/]
+
+      inc_file = li.chop.match(/(?<=^include::).+.adoc(?=\[\])/i).to_s
+      inc_file = inc_file.sub(/^\{find\}/, '')
+      path = inc_file.sub(/^#{docsdir}\//, '')
+      path = path.sub(/#{exts}/, '')
+      parent = f
+      item = [inc_file, path, parent]
+      incs.push item
+
+    end
+    title = li
+  end
+end
+
+i = 0
+reqs.each do |req, f, title, chapter, doctitle|
+  i += 1
+  link = ''
+  # TODO: - find better solution for sanitized titles:
+  title = title.delete('`').delete("'").delete('*')
+
+  rid = /[^,]*\s*id\s*=\s*(\w+-?[0-9]+)\s*,.*/.match(req)[1]
+  version = /(?<=version=)\d+/.match(req)
+
+  f.gsub!(/^chapters\//, '')
+  f.gsub!(/.adoc$/, '')
+
+  $reqfixes.each do |id, fix|
+    next unless id == rid
+    link = "#{fix}.html##{rid}"
+    break
+  end
+
+  f = f.sub(/^chapters\//, '')
+  ref = "<a class=\"link\" href=\"#{link}\"><emphasis role=\"strong\">#{title}</emphasis>  </a>"
+  breadcrumb = "<a href=\"#{f}\">#{chapter} / #{doctitle}</a>"
+  row = "<tr> <th scope=\"row\">#{i}</th> <td style=\"white-space:pre;\">#{rid}</td><td>#{version}</td> <td>#{ref}</td> <td>#{f}</td> </tr>"
+
+  rows.push(row)
+end
+
+Asciidoctor::Extensions.register do
+  block_macro :requirements do
+    process do |parent, _target, _attrs|
+      content = %(<h2 id="requirements"><a class="anchor" href="#requirements"></a><a class="link" href="#requirements">Requirements</a></h2>
+<div class="panel panel-default"> <div class="panel-heading"><h4>Requirements</h4></div>
+<table class="table"> <thead> <tr>
+<th>#</th> <th>ID</th><th>Version</th> <th>Title</th> <th>Source Document</th>
+</tr> </thead>
+<tbody>
+#{rows.join}
+</tbody>
+</table> </div>)
+
+      create_pass_block parent, content, {}
+    end
+  end
+end

data/lib/extensions/requirement_block.rb

@@ -0,0 +1,50 @@
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+include ::Asciidoctor
+
+Extensions.register do
+  block do
+    named :req
+    on_contexts :open, :paragraph, :example, :listing, :sidebar, :pass
+    name_positional_attributes 'number', 'version'
+
+    process do |parent, reader, attrs|
+      # Add pass characters here to prevent html character replacements for < > tags
+      pass = '++++'
+      attrs['name'] = 'requirement'
+      attrs['caption'] = 'Requirement: '
+      id = attrs['id']
+      nl = ''
+
+      begin
+        # downcase the title and replace spaces with underscores.
+        #    Also replacing special HTML entities:
+        #    &quot; = "
+        #    &amp;  = &
+        downcased_title = attrs['title'].downcase.tr(' ', '_').gsub('"', '&quot;')
+        san_title = attrs['title'].gsub(/&/, '&amp;').delete('`').delete("'").delete('*')
+      rescue Exception => msg
+        puts msg
+        # If no title exists on the Req block, throw an exception
+        puts '[ERROR] Requirement block title missing'
+      end
+
+      alt = %(<div class=\"panel panel-primary\">
+<div class=\"panel-heading\">
+<h3 class=\"panel-title\" data-toc-skip>
+<a class=\"anchor\" href=\"##{id}\"></a>
+<a class=\"link\" href=\"##{id}\"><emphasis role=\"strong\">Requirement: #{id}:</emphasis> #{san_title} </a> (ver. #{attrs['version']})
+</h3>
+</div>
+<div class=\"panel-body\">)
+
+      close = '</div></div>'
+
+      # concatenate all generated lines and prepend before the original content
+      concat_lines = reader.lines.unshift(pass, alt, pass, nl)
+      concat_lines.push(nl, pass, close, pass)
+
+      create_block parent, :open, concat_lines, attrs, content_model: :compound
+    end
+  end
+end

data/lib/extensions/todo_block.rb

@@ -0,0 +1,16 @@
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+include ::Asciidoctor
+
+Extensions.register do
+  block do
+    named :TODO
+    on_contexts :open, :paragraph, :example, :listing, :sidebar, :pass
+
+    process do |parent, reader, attrs|
+      attrs['name'] = 'todo'
+      attrs['caption'] = 'Todo'
+      create_block parent, :admonition, reader.lines, attrs, content_model: :compound
+    end
+  end
+end

data/lib/extensions/utils/block.rb

@@ -0,0 +1,36 @@
+# Helper methods handling whether to output inline content or a block.
+# Will read the attributes of the current macro and output a HTML string that is either
+# inline or a block (float-right).
+module Context
+  # @param attributes [Array] attributes passed by the inline macro
+  # @param target [String] the target text
+  # @param pattern [String] the target url
+  # @param label [String] an optional status label, used to display if a task/issue is open or closed
+  # @return [String] the raw HTML to be included in the target document
+  def self.format(attributes, target, pattern, label)
+    block = false
+    block = true if attributes.key? 'block'
+
+    if target[0] == "\:"
+      block = true
+      target[0] = ''
+    end
+
+    url = "#{pattern}/#{target}"
+
+    html = if block
+             if pattern == 'unknown'
+               "<div style=\"float:right;padding-left:0.1em;\"><span class=\"label label-#{label}\" data-toggle=\"tooltip\" title=\"Missing config\">#{target}</span></div>"
+             else
+               "<div style=\"float:right;padding-left:0.1em;\"><a href=\"#{url}\"><span class=\"label label-#{label}\">#{target}</span></a></div>"
+                    end
+           else
+             if pattern == 'unknown'
+               "<span class=\"label label-#{label}\" data-toggle=\"tooltip\" title=\"Missing config\">#{target}</span>"
+             else
+               "<a href=\"#{url}\"><span class=\"label label-#{label}\">#{target}</span></a>"
+                    end
+           end
+    html
+  end
+end

data/lib/extensions/utils/labels.rb

@@ -0,0 +1,18 @@
+# A simple helper method handles the status of the target text.
+# This is used to display whether a GitHub issue or a Jira ticket
+# is open or closed etc.
+module Labels
+  # @param attrs [Array] attributes passed by the inline macro
+  # @return [String] the status and/or label to be displayed
+  def self.getstatus(attrs)
+    status = attrs['status']
+    if status == ('done' || 'closed')
+      label = 'success'
+    elsif status == 'open'
+      label = 'warning'
+    else
+      status = 'unknown'
+      label = 'default'
+    end
+  end
+end

data/lib/extensions/utils/scanner.rb

@@ -0,0 +1,20 @@
+module Sform
+  def self.trim(s)
+    s = s.gsub(/^#{$srcdir}\//, '') unless s.nil?
+    s = s.gsub(/(\.adoc)/, '') unless s.nil?
+  end
+
+  def self.underscorify(t)
+    t = t.downcase.gsub(/(\s|-)/, '_')
+    # document attribute idprefix must be seet to empty, if not
+    # the default value is an underscore and the following line is required
+    # t = t.prepend('_') unless t.match(/^_/)
+    t = t.gsub(/___/, '_').delete('`')
+  end
+
+  def self.titleify(t)
+    t = t.tr('_', ' ')
+    t = t.lstrip
+    t = t.split.map(&:capitalize).join(' ')
+  end
+end

data/lib/html_chunker.rb

@@ -0,0 +1,107 @@
+require 'asciidoctor'
+
+# Chunks the HTML output generated by the HTML5 converter by chapter.
+#
+class MultipageHtml5Converter
+  include Asciidoctor::Converter
+  include Asciidoctor::Writer
+
+  register_for 'multipage'
+  EOL = "\n".freeze
+
+  def initialize(backend, opts)
+    super
+    basebackend 'html'
+    @documents = []
+  end
+
+  def convert(node, transform = nil)
+    transform ||= node.node_name
+    send transform, node if respond_to? transform
+  end
+
+  def document(node)
+    indexconfigs = {
+      'stylesheet' => 'styles/main.css',
+      'find' => '',
+      'docinfodir' => 'headers',
+      'docinfo1' => 'true'
+    }
+    node.blocks.each(&:convert)
+    node.blocks.clear
+    master_content = []
+    master_content << %(= #{node.doctitle})
+    master_content << (node.attr 'author') if node.attr? 'author'
+    master_content << ''
+    # @documents.each do |doc|
+    #   sect = doc.blocks[0]
+    #   sectnum = sect.numbered && !sect.caption ? %(#{sect.sectnum} ) : nil
+    #   filename = doc.attr 'docname'
+    #   filename = filename.sub(/^_/, '')
+    #   master_content << %(== <<#{filename}#,#{sectnum}#{sect.captioned_title}>> +)
+    # end
+    master_content << ''
+    master_content << 'requirements::[]'
+    Asciidoctor.convert master_content, doctype: node.doctype, header_footer: true, safe: node.safe, attributes: indexconfigs
+  end
+
+  def section(node)
+    doc = node.document
+    node.id.gsub!(/_2$/, '') if node.id[/_2$/]
+    configs = doc.attributes.clone
+    configs['noheader'] = ''
+    configs['doctitle'] = node.title
+    configs['backend'] = 'html'
+    page = Asciidoctor::Document.new [], header_footer: true, doctype: doc.doctype, safe: doc.safe, parse: true, attributes: configs
+
+    page.set_attr 'docname', node.id
+    reparent node, page
+
+    page.blocks << node
+    @documents << page
+    ''
+  end
+
+  def reparent(node, parent)
+    node.parent = parent
+    node.blocks.each do |block|
+      reparent block, node unless block.context == :dlist
+      if block.context == :table
+        block.columns.each do |col|
+          col.parent = col.parent
+        end
+        block.rows.body.each do |row|
+          row.each do |cell|
+            cell.parent = cell.parent
+          end
+        end
+      elsif block.context == :dlist
+        block.parent = parent
+        block.items.each do |i|
+          reparent i[1], parent if i[1].respond_to? 'parent'
+        end
+      end
+    end
+  end
+
+  def write(output, target)
+    outdir = ::File.dirname target
+    puts '[CHUNKED HTML] Generating chapters:'
+    @documents.each do |doc|
+      filename = doc.attr 'docname'
+      filename = filename.sub(/^_/, '')
+      outfile = ::File.join outdir, %(#{filename}.html)
+      puts "[CHAPTER] #{outfile}"
+      ::File.open(outfile, 'w') do |f|
+        f.write doc.convert
+      end
+    end
+    chunked_target = target.gsub(/(\.[^.]+)$/, '-chunked\1')
+    puts "[HTML INDEX] Generating index at #{chunked_target}"
+    ::File.open(chunked_target, 'w') do |f|
+      f.write output
+    end
+    load "postprocessors/generate_toc.rb"
+    load "postprocessors/fulltext_search.rb"
+  end
+end

data/lib/postprocessors/fulltext_search.rb

@@ -0,0 +1,48 @@
+require 'nokogiri'
+require 'fileutils'
+require 'open-uri'
+
+json = ''
+gendir = 'generated-docs' # TODO: - do not hardcode
+replacements = /"|\n|«|»
|\s\s/
+
+html_files = Dir.glob("#{gendir}/**/*.html")
+
+html_files.each do |file|
+  # Skip the search results and index pages
+  next if file == "#{gendir}/search.html" || file[%r{^#{gendir}\/index}]
+
+  page = Nokogiri::HTML(open(file))
+  file.sub!(%r{^#{gendir}\/}, '')
+  slug = file.sub(/\.html$/, '')
+
+  h2 = page.css('h2').text
+  text = page.css('p').text.gsub(replacements, ' ')
+
+  content = %(
+  "#{slug}": {
+      "id": "#{slug}",
+      "title": "#{h2}",
+      "url": "#{file}",
+      "content": "#{text}"
+    },\n)
+  json += content
+end
+
+jsonindex = %(<script>
+window.data = {
+
+#{json}
+
+};
+</script>)
+
+marker = '{{searchdata}}'
+searchpage = "#{gendir}/search.html"
+
+data = File.read(searchpage)
+filtered_data = data.sub(marker, jsonindex)
+
+File.open(searchpage, 'w') do |f|
+  f.write(filtered_data)
+end