jekyll_aspec 1.0.0.pre.alpha → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c77631b5967f60ae7f3f0ab335f0445b4c09e174
-  data.tar.gz: 8eba5d605e5d4d1d2425cccb6495114f81669497
+  metadata.gz: a7660532ed66dd03c81835079b3f1f2c57a495a7
+  data.tar.gz: 9fd9c8f89aad34a1498ea52cd3f04b021db3a564
 SHA512:
-  metadata.gz: cfc99e19a9cb848003dc84d99e2f5c5cc61f2702bcfdfd915f89db0bc0375e1737abe9bb9a04c6ecb1d711400ca93d4200c7779e2d5146e20e5fdf7027046ce0
-  data.tar.gz: 48268e49f8269b28e5a449e17aa09f009145488a979cc5be4782ba565cfd290ecb020d48b3add72a25c32499a943293f2da8f40308128bc11f9d0e14d2740319
+  metadata.gz: a13f2ee35c2a0082ecb6c11d4ddce5c76c6145ccc16113912fcad43bb4ca751d7560d4ed03b8465489be8a22f21d7533d384ecc3bdcc6cea59847e26bf248ef0
+  data.tar.gz: 141f495acb546d4ef8a8e0037b6e9d099fc4803d11455af2149e0ab3ec59b8fae1a9d9b1e14a68c42b57563602f1c3cf122693aafe05b83b74e2a0ec6ae454e0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jekyll_aspec (1.0.0.pre.alpha)
+    jekyll_aspec (1.0.0)
       asciidoctor (>= 1.5.0)
 
 GEM

data/README.adoc

@@ -0,0 +1,54 @@
+= Jekyll Aspec
+
+image:https://travis-ci.org/bsmith-n4/jekyll_aspec.svg?branch=master["Build Status", link="https://travis-ci.org/bsmith-n4/jekyll_aspec"]
+
+A selection of Asciidoctor extensions designed to used to write some AsciiSpec with Jekyll. 
+
+These extensions add custom blocks for Requirements and attempts to smartly handle inter-document auto-linking functionality.
+
+== Motivation
+
+Jekyll is a very flexible and speedy tool for generating static HTML pages. 
+The `jekyl-asciidoc` gem adds Asciidoctor functionality but it lacks a few features due to the way it handles multiple source files. As each `.adoc` file is consumed individually, we lose the ability to automatically format inter-document cross-references. This plugin is a group of extensions that performs some directory walking, stores the location of titles and anchors so that cross references in a Jekyll project are resolved automatically. 
+
+Additional features are
+
+* Custom block for ``TODO``s
+* Requirements Block with versioning
+* Requirements block macro that creates a Table of Contents of declared Requirements
+* Inline Callout macro to arbitrarily add callouts
+* Inline Task macro to link to Jira tickets or Github Issues
+* Inline Repo Macro to link to specific files or lines on GitHub
+* A HTML postprocessor to correct some minor fixes and invalid tags created by Asciidoctor
+
+When these custom extensions are combined with other recommended gems such as `asciidoctor-bibtex` and `asciidoctor-latex`, you can achieve quite high quality, speedy HTML documentation for technical projects with the benefits of a Jekyll build. It's recommended to use the `html-proofer` gem which will validate all links created with these extensions.
+
+== Installation
+
+Add `jekyll_aspec` to your Jekyll Gemfile:
+
+```ruby
+group :jekyll_plugins do
+  gem 'jekyll-asciidoc'
+  gem 'jekyll_aspec'
+end
+```
+
+Or install it yourself as:
+
+ $ gem install jekyll_aspec
+
+== Docs
+
+Please refer to the `docs` directory for some basic documentation on extended Asciidoctor features:
+
+*<<docs/requirement-block#,[req] - Requirement Block>>*: Add requirements with custom formatting. +
+*<<docs/todo-block#,[TODO] - Todo Block>>*: Add a custom TODO admonition block. +
+
+== Contributing
+
+This gem is under heavy initial development and there are still many kinks to work out. The areas to be improved upon include performance enhancements, proper handling of file IO / directory walking and, of course, documentation. Bug reports and pull requests are welcome on GitHub at https://github.com/bsmith-n4/jekyll_aspec.
+
+== License
+
+The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT License].

data/Rakefile

@@ -1,8 +1,8 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
 require 'test/unit'
 
 task :default => :test
 
 task :test do
-  ruby "test/suite.rb"
+  ruby 'test/suite.rb'
 end

data/docs/inline-task.adoc

@@ -0,0 +1,34 @@
+= Inline Task Macro
+:toc:
+
+Usage::
+[source,asciidoc]
+task:target[title]
+
+The `inline task macro` creates hyperlinks to Jira task management and GitHub issue-tracking systems.
+Optionally, it will render the links differently to reflect the status of the tasks if a task info file is provided.
+
+Note that in case two colons are given instead of only one after `task`, the task link will be moved to the sidebar.
+
+Attributes::
+* *target:* The project prefix followed by a hyphen and the task number or ID (e.g. `23`).
+* *title:* (optional) The text that will be displayed as an anchor in the generated hyperlink.
+
+== Configuration
+
+The target pattern needs to be specified in a document attribute:
+
+`:task-pattern: http://www.myorg.github.com/myrepo/issues/`
+
+For a Jekyll build, this can be added in the Jekyll `pass:[_config.yml]` to be passed to all documents:
+
+```yaml
+asciidoctor:
+  attributes:
+    task-pattern: http://www.myorg.github.com/myrepo/issues/
+```
+
+== Examples
+
+A bug has already ``+++task:35[]+++`` been filed...
+

data/docs/requirement-block.adoc

@@ -0,0 +1,56 @@
+= Requirements Block
+
+Usage::
+
+ .title
+ [req,id=RSL-3,version=1]
+ --
+ Contents of the requirement
+ --
+
+
+Attributes::
+* *title* (required):  An anchor is derived from the requirement title and embedded at the beginning of the rendered output.
+* *ID:* (required) The ID in the form *<Prefix>-<Number>*, used to generate an anchor
+* *version*: (required) value is a non-negative integer.
+
+NOTE: Omitting any of the above attributes will print an error to the console and insert a warning text in the generated document.
+* *delimiter*: Lines containing only two hyphens `--` delimit the block. This is required if the block contains empty lines or nested formatting.
+
+== ID Pattern
+
+The purpose of the `<Prefix>-<Number>` ID is to ensure that Requirements are both unique and easily referenceable.
+Currently, the ID may be any string, but should conform to the following conventions:
+
+*<Prefix>*: :: `R` (requirement) followed by the project prefix (i.e. `SL` for `stdlib`)
+*<Number>*: :: The requirement number, currently not validated.
+A validation stage for requirement IDs (detecting duplicates, for instance) is planned.
+
+Example::
+
+The following example demonstrates how to document Requirement pass:[#]3 for stdlib Version 1;
+
+ .This is the title
+ [req,id=RSL-3,version=1]
+ --
+ My Super Requirement
+ --
+
+
+*Req. RSL-3: <<This_is_the_title,This is the title>> (ver. 1)* +
+My Super Requirement
+
+
+== Xrefs
+
+Cross-referencing requirements is done using the syntax `\<<Req-ID,Optional Link Text>>`, e.g. for the following requirement:
+
+ [req,id=ROPR-14603,version=1]
+ --
+ ...
+ --
+
+
+can be cross-referenced using the following syntax
+
+ See <<Req-ROPR-14603>>, or see also <<Req-ROPR-14603,confirm the booking>>.

data/docs/todo-block.adoc

@@ -0,0 +1,48 @@
+= TODO Block
+
+== Usage
+
+[source,asciidoc]
+----
+// Simple use
+
+[TODO]
+Don't forget
+----
+
+===  Delimiters 
+
+Delimiters are required if the block contains empty lines or nested blocks. +
+The following delimiters may be used:
+
+[source,subs=macros]
+----
+====
+--
+pass:[++++]
+****
+pass:[----]
+----
+
+Examples:: 
+[source,asciidoc]
+----
+.Block Title (optional)
+[TODO]
+--
+Don't Forget!
+
+. Resolve an issue
+.. Don't break anything
+--
+
+// or 
+
+[TODO]
+++++
+Don't divide by zero.
+
+* Add 1 to infinity.
+++++
+
+----

data/jekyll_aspec.gemspec

@@ -10,9 +10,16 @@ Gem::Specification.new do |spec|
   spec.email         = ["brian.smith@numberfour.eu"]
 
   spec.summary       = %q{Asciidoctor extensions for use as a Jekyll plugin}
+  spec.description   = %q{This plugin is a group of Asciidoctor extensions that perform directory walking, 
+                          resolving the location of titles and anchors in all adoc files so that inter-document
+                          cross-references in a Jekyll project are resolved automatically. Also included are some 
+                          custom macros and blocks that are useful for techinical writing.}
   spec.homepage      = "https://github.com/bsmith-n4/jekyll_aspec"
   spec.license       = "MIT"
 
+  # This gem will work with 2.0 or greater.
+  spec.required_ruby_version = '>= 2.0'
+
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end

data/lib/extensions/autoxrefs.rb

@@ -1,117 +1,23 @@
 require 'asciidoctor/extensions'
 require 'pathname'
+require_relative 'utils/xref_helper'
 
 include ::Asciidoctor
 
-# Find all Adoc Files
-adoc_files = Dir.glob('**/*.adoc')
+mismatches = Xrefs.list_xrefs
 invoc = Dir.pwd
 
-# Make some arrays available
-titles = []
-anchors = []
-xrefs = []
-mismatches = []
-
-replacement = ''
-
-def trim(s)
-  s.gsub!(/_docs\//, '')
-  s.gsub!(/(\.adoc|\.md|\.html)/, '')
-end
-
-def targetify(t)
-  # make all chars lowercase and substitute spaces with hyphens
-  t.downcase.gsub(/\s/, '-')
-end
-
-adoc_files.each do |file_name|
-  lc = 0
-
-  File.read(file_name).each_line do |li|
-    lc += 1
-
-    # Match all <<xrefs>> exluding Requirements
-    if li[/\<\<(?!Req)(.+?)\>\>/]
-
-      text = ''
-      target = ''
-      path = trim(file_name)
-      xref = li.chop.match(/\<\<(?!Req)(\S.+?)\>\>/i).captures[0].to_s
-
-      if xref[/,/]
-        target = xref.downcase.gsub(/,.+/, '').gsub(/\s/, '-')
-        text = xref.gsub(/.+,/, '').lstrip!
-        xref = xref.sub(/,.+/, '')
-        path = file_name
-      else
-        target = xref.downcase.gsub(/\s/, '-')
-        text = xref
-      end
-
-      item = [xref, path, file_name, text, target]
-      xrefs.push item
-
-      # Match .Titles and = Section Titles
-    elsif li[/(^(\.\S\w+)|^(\=+\s+?\S+.+))/]
-
-      # Add check if none found (captures nil)
-      title = li.chop.match(/(?!=+\s)(\S+.+?)$/i).captures[0]
-      title.sub!(/\.(?=\w+?)/, '') if title[/\.(?=\w+?)/]
-      path = trim(file_name)
-      item = [title, path, file_name]
-      titles.push item
-
-    # Match [[anchors]]
-    elsif li[/\[\[.+?\]\]/]
-
-      # Add check if none found (captures nil)
-      anchor = li.chop.match(/(?<=\[\[).+?(?=\]\])/).to_s
-
-      if anchor[/,/]
-        anchor = anchor.match(/(?<=\[\[)(?:|[\w+?_:][\w+?:.-]*)(?=,.+?\]\])/).to_s
-        text = anchor.sub(/.+?,/, '')
-        text = text.sub(/\]\]$/, '')
-      end
-
-      path = trim(file_name)
-      item = [anchor, path, file_name, text]
-      titles.push item
-
-    end
-  end
-end
-
-# Run through each xref and check for matching titles
-xrefs.each do |xref, xpath, xfile, xtext, xtarget|
-  # check xrefs against titles
-  titles.each do |ttext, tpath, tfile, _tdisp|
-    # puts "checking #{ttext} against #{xref}"
-    next unless ttext == xref
-    tpath = 'index' if tpath.to_s.empty?
-    # If the paths are not the same (xref and title not the same document) do the following
-    next unless tpath != xpath
-
-    # puts "Title \"#{ttext}\" in #{tfile} - mismatched xref \"#{xref}\" to different doc - #{xpath}"
-    xtform = targetify(xtarget)
-    detail = [xref, xtarget, xtext, xpath, xfile, ttext, tpath, tfile, xtform]
-    mismatches.push detail
-  end
-end
-
 Extensions.register do
   preprocessor do
     process do |document, reader|
       fixes = []
       i = 0
 
-      # Block is loaded once per document!!!
-      # for each malformed xref
+      # TODO - remove unused elements (prepended with _) from the helper method in utils/xref_helper
       mismatches.each do |_xref, _xtarget, xtext, _xpath, xfile, _ttext, _tpath, tfile, xtform|
-        # FIXME: This directory is empty in POSTS - breaks conversion
         docfile = document.attributes['docfile'].sub(/^#{invoc}\//, '')
-        trim(docfile)
-
+        Xrefs.trim(docfile)
+        
         next unless docfile.to_s == xfile
 
         # calculate the relative path between source and target
@@ -129,8 +35,6 @@ Extensions.register do
         if li[/\<\<(?!Req)(.+?)\>\>/]
 
           mismatches.each do |xref, xtarget, xtext, _xpath, _xfile, _ttext, _tpath, _tfile, _relpath|
-            # check if the line contains the original xref
-
             next unless li[/\<\<#{xref}(,.+)?\>\>/]
             fixes.each do |x|
               if x[/#{xtarget}/]
@@ -140,7 +44,6 @@ Extensions.register do
             end
             i += 1
           end
-
         else
           replacement = ''
         end

data/lib/extensions/html_postprocessor.rb

@@ -2,6 +2,7 @@ require 'asciidoctor/extensions'
 
 include ::Asciidoctor
 
+# Strip bogus tags generated by Asciidoctor
 Extensions.register do
   postprocessor do
     process do |document, output|

data/lib/extensions/inline_callout_macro.rb

@@ -2,6 +2,8 @@ require 'asciidoctor/extensions'
 
 include ::Asciidoctor
 
+# @example Basic Usage
+#   See call:1[] for details
 Asciidoctor::Extensions.register do
   inline_macro do
     named :call
@@ -9,4 +11,4 @@ Asciidoctor::Extensions.register do
       Asciidoctor::Inline.new(parent, :callout, target.to_i).convert
     end
   end
-end
+end

data/lib/extensions/inline_cwiki_macro.rb

@@ -4,18 +4,24 @@ require_relative 'utils/block'
 
 include ::Asciidoctor
 
+# @example Basic Usage
+#   See cwiki:topic[] for details
+# @example Block Use
+#   Already documented. cwiki::topic[]
 Extensions.register do
   inline_macro do
     named :cwiki
 
     process do |parent, target, attrs|
-      pattern =
-        (parent.document.attr 'cwiki-pattern') ||
-        'https://confluence.numberfour.eu/display/%s'
+      pattern = parent.document.attr 'cwiki-pattern'
+      if pattern.nil? 
+        warn "asciidoctor: WARNING: Attribue 'cwiki-pattern' for inline repo macro not defined"
+        pattern = "unknown"
+      end
       url = pattern % target
 
       label = Labels.getstatus(attrs)
-      html = Context.form(attrs, target, url, label)
+      html = Context.format(attrs, target, url, label)
       (create_pass_block parent, html, attrs).render
     end
   end

data/lib/extensions/inline_repo_macro.rb

@@ -2,29 +2,34 @@ require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
 
 include ::Asciidoctor
 
+url = ''
+file = ''
+line = ''
+formattedurl = ''
+text = ''
+
 # Link to a file on GitHub.
 #
 # repo:<repository>:<file>:<line>[]
 #
-#   Examples:
+# The target should be set using document attributes prefixed by 'repo_'.
 #
+# @example Attribute configuration
+#   :repo_dockerfiles: www.github.com/exampleuser/dockerfiles/issues 
+# @example Simple Use
 #   repo:dockerfiles:ansible/Dockerfile_template[]
+# @example Link to repo and line number
 #   repo:dockerfiles:ansible/Dockerfile_template:2[]
+# @example Link to repo, branch and line number
 #   repo:dockerfiles:ansible/Dockerfile_template:5[branch="AS_v0.0.10"]
+# @example Link to repo and line number (alternate use)
 #   repo:dockerfiles:ansible/Dockerfile_template[line="5",branch="AS_v0.0.10"]
-#
-
-url = ''
-file = ''
-line = ''
-formattedurl = ''
-text = ''
-
 Extensions.register do
   inline_macro do
     named :repo
 
     process do |parent, target, attrs|
+      # @todo fix handling of use within cells. This is done using the context.
       if parent.context.to_s == 'cell'
         warn %([Hell in a cell] cell with repo link must have 'asciidoc format')
       end
@@ -66,6 +71,11 @@ Extensions.register do
         end
       end
 
+      if formattedurl.nil? 
+        warn "asciidoctor: WARNING: Attribue 'repo_...' for inline repo macro not defined"
+        pattern = "unknown"
+      end
+
       html = %(<a href=\"#{formattedurl}\" style=\"padding-right:2px;\">
                   <span class=\"label label-#{label}\" style=\"font-weight: 400;
                   font-size:smaller;\">

data/lib/extensions/inline_task_macro.rb

@@ -4,18 +4,24 @@ require_relative 'utils/block'
 
 include ::Asciidoctor
 
+# @example Basic Usage
+#   See task:101[] for details
+# @example Block Use
+#   Already completed. task::101[]
 Extensions.register do
   inline_macro do
     named :task
 
     process do |parent, target, attrs|
-      pattern =
-        (parent.document.attr 'task-pattern') ||
-        'https://jira.numberfour.eu/browse/%s'
+      pattern = parent.document.attr 'task-pattern'
+      if pattern.nil? 
+        warn "asciidoctor: WARNING: Attribue 'task-pattern' for inline task macro not defined"
+        pattern = "unknown"
+      end
       url = pattern % target
-      # Some utility functions used by similar inline macros
+
       label = Labels.getstatus(attrs)
-      html = Context.form(attrs, target, url, label)
+      html = Context.format(attrs, target, url, label)
       (create_pass_block parent, html, attrs).render
     end
   end

data/lib/extensions/replace_regex.rb

@@ -1,6 +1,8 @@
+# Used by Jekyll during conversion
 module Jekyll
   # A Liquid Template Filter for using regular expressions
   module RegexFilter
+    # Simple replacement
     def replace_regex(input, regex_string, replace_string)
       regex = Regexp.new regex_string
       input.gsub regex, replace_string

data/lib/extensions/req_preprocessor.rb

@@ -1,8 +1,9 @@
 require 'asciidoctor/extensions'
 
 include ::Asciidoctor
+
 # Preprocessor that strips the << tags
-# FIXME: may break conversion if line ends with >>
+# @todo may break conversion if line ends with >>
 
 req = '<<req-'
 brackets = /<<|>>/

data/lib/extensions/req_refs.rb

@@ -2,26 +2,30 @@ require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
 
 include ::Asciidoctor
 
+# @todo check if all code before the macro can be moved into util directory as helper methods
+
+# @todo Don't do this
 adoc_files = Dir.glob('**/*.adoc')
+# @todo Retrieve these via document attributes, should not be hardcoded
+docsdir = '_docs'
 exts = '(\.adoc|\.md|\.html)'
 
 rpath = nil
 rtext = nil
+orphan = false
+
 reqs = []
 inc_reqs = []
 com_reqs = []
 incs = []
 xrefs = []
+
 xref_base = ''
 
-blockrx = %r(^\/{4,}$)
+blockrx = %r{^\/{4,}$}
 linerx = %r{^//(?=[^/]|$)}
 
-orphan = false
-
-# Retrieve this via document attribute
-docsdir = '_docs'
-
+# @todo called helper method here
 def trim(s)
   s.gsub!(/_docs\//, '')
   s.gsub!(/(\.adoc|\.md|\.html)/, '')
@@ -90,11 +94,16 @@ end
 # Sort (in-place) by numberic ID
 reqs.sort_by!(&:first)
 
+# @todo convert to formal 
 Extensions.register do
   inline_macro do
     named :requirement_autoxref
 
     # Regex-based, will match "See Req-ROPR-123 for..."
+    # Will also match <<Req-ROPR-123>>
+    # @todo this is a heavy-handed approach to matching all 
+    # xrefs. Find a better way to autolink xrefs that doesn't involved the
+    # use of the req-preprocessor
     match /(Req-\w+-?\d+)/
 
     # match id with  Req-\w+-?(\d+)

data/lib/extensions/requirement_block.rb

@@ -2,50 +2,55 @@ 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;")
-      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\">
-            <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, :admonition, concat_lines, attrs, content_model: :compound
+# @example Delimited Requirement Block with Title
+#   .My Requirement
+#   [req,id=RA-1,version=1]
+#   --
+#   Contents of the requirement
+#   --
+class RequirementBlock < Extensions::BlockProcessor
+  use_dsl
+  named :req
+  on_contexts :open, :paragraph, :example, :listing, :sidebar, :pass
+  name_positional_attributes "number", "version"
+
+  # Read the parent attributes and create a Requirement Admonition block
+  def process 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.
+      # @todo use utility methods here?
+      downcased_title = attrs["title"].downcase.tr(" ", "_").gsub('"', "&quot;")
+      san_title = attrs["title"].gsub(/&/, "&amp;")
+    rescue Exception => msg
+      # puts msg
+      # If no title exists on the Req block, throw an exception
+      warn %(asciidoctor: WARNING: Requirement block title missing)
     end
+
+    alt = %(
+    <div class=\"panel panel-primary\">
+      <div class=\"panel-heading\">
+        <h3 class=\"panel-title\">
+          <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)
+
+    # @todo use a regular pass block in this instance
+    create_block parent, :admonition, concat_lines, attrs, content_model: :compound
   end
 end

data/lib/extensions/requirement_block_macro.rb

@@ -0,0 +1,28 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+require_relative 'utils/req_macro_walker'
+
+include ::Asciidoctor
+
+# @example Requirement Block Macro Use
+#   requirements::[]
+class RequirementsBlockMacro < Extensions::BlockMacroProcessor
+  use_dsl
+  named :requirements
+
+  # Read the parent attributes and create a list of requirements in an appendix style
+  def process(parent, target, attrs)
+    rows = Reqs.list_reqs
+    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>Document</th>
+      </tr> </thead>
+      <tbody>
+        #{rows.join}
+      </tbody>
+      </table> </div>)
+
+    create_pass_block parent, content, {}
+  end
+end

data/lib/extensions/todo_block.rb

@@ -2,11 +2,18 @@ require "asciidoctor/extensions" unless RUBY_ENGINE == "opal"
 
 include ::Asciidoctor
 
+# @example A delimited TODO block
+#   [TODO]
+#   --
+#   Don't Forget!
+#   --
 class TodoBlock < Extensions::BlockProcessor
   use_dsl
   named :TODO
   on_contexts :open, :paragraph, :example, :listing, :sidebar, :pass
 
+  # Read the parent attributes and create a TODO 
+  # admonition block
   def process parent, reader, attrs
     attrs['name'] = 'todo'
     attrs['caption'] = 'Todo'

data/lib/extensions/utils/block.rb

@@ -1,5 +1,13 @@
+# 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
-  def self.form(attributes, target, url, label)
+  # @param attributes [Array] attributes passed by the inline macro
+  # @param target [String] the target text
+  # @param url [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, url, label)
     block = false
     block = true if attributes.key? "block"
 

data/lib/extensions/utils/labels.rb

@@ -1,4 +1,9 @@
+# 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")

data/lib/extensions/utils/req_macro_walker.rb

@@ -0,0 +1,110 @@
+# Special handling for linking to Requirements.
+# These are mainly used by the Requirement Appendix (requirement_block_macro)
+#
+module Reqs
+  # Recursively globs all files with the .adoc extension and matches cross-references
+  # to Requirements. The special handling here is that we detect if the target 
+  # requirement is commented, in a source block or included.
+  #
+  # @return [Array] An array of the IDs and paths to requirements in generated HTML files
+  def self.list_reqs
+    # @todo This should be configurable, or at least not hardcoded
+    exts = "(\.adoc|\.md|\.html)"
+    docsdir = '_docs'
+
+    title = nil
+    chapter = nil
+    doctitle = nil
+
+    reqs = []
+    rows = []
+    # For commented requirements
+    coms = []
+    # For includes
+    inc_reqs = []
+    incs = []
+
+    commentblockrx = '/^\/{4,}$/'
+    commentlinerx = '/^//(?=[^/]|$)/'
+
+    # @todo Already defined in Xref util?
+    def trim(s)
+      s.gsub!(/_docs\//, '')
+      s.gsub!(/(\.adoc|\.md|\.html)/, '')
+    end
+
+    # @todo Dont do this? Find a better way of handling all source adoc files.
+    adoc_files = Dir.glob('**/*.adoc')
+
+    adoc_files.each do |f|
+      inc = false
+      commented = false
+
+      File.read(f).each_line do |li|
+        incommentblock ^= true if li[commentblockrx]
+        commented = true if li[commentlinerx]
+        inc = true if li[/published: false/]
+
+        doctitle = /(?<=title:\s).+/.match(li) if li[/^title:\s+\w.+/]
+        chapter = /(?<=chapter:\s).+/.match(li) if li[/^chapter:\s+\w.+/]
+
+        if li[/^\[\s*req\s*,\s*id\s*=\s*\w+-?[0-9]+\s*,.*/]
+          title.sub!(/^\./, '')
+          req = [li.chop, f, title, chapter, doctitle]
+
+          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
+          path = inc_file.sub(/^#{docsdir}\//, '')
+          path = path.sub(/#{exts}/, '')
+          parent = f
+          item = [inc_file, path, parent]
+          incs.push item
+
+        end
+        title = li
+      end
+    end
+
+    # Sort included reqs and correct the path to the parent (including doc)
+    # Push this back into 'normal' requirements array for regular processing
+    inc_reqs.each do |l, f, title, chapter, doctitle|
+      incs.each do |incfile, _incpath, parent|
+        if f == incfile
+          item = [l, parent, title, chapter, doctitle]
+          reqs.push item
+        end
+      end
+    end
+
+    # Remove dupes
+    reqs.uniq!
+
+    i = 0
+    reqs.each do |req, f, title, chapter, doctitle|
+      i += 1
+
+      id = /[^,]*\s*id\s*=\s*(\w+-?[0-9]+)\s*,.*/.match(req)[1]
+      version = /(?<=version=)\d+/.match(req)
+
+      f.gsub!(/^_docs\//, '')
+      f.gsub!(/.adoc$/, '')
+
+      link = "#{f}/index##{id}"
+      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>#{id}</td><td>#{version}</td> <td>#{ref}</td> <td>#{breadcrumb}</td> </tr>"
+
+      rows.push(row)
+    end
+  end
+end

data/lib/extensions/utils/xref_helper.rb

@@ -0,0 +1,122 @@
+# Helper methods for common xref processing.
+#
+module Xrefs
+  # Trims a path of a given source document to exclude the docs directory
+  # and file extension. This is used to calculate the target directory 
+  # of generated HTML files given default permalink settings.
+  #
+  # @param path [String] the path of the source document relative to the project root
+  # @return [String] the formatted path
+  def self.trim(path)
+    trimmed = path.gsub(/_docs\//, '')
+    trimmed.gsub(/(\.adoc|\.md|\.html)/, '')
+  end
+
+  # Formats a string to be permalink-friendly. This simply
+  # downcases the string an substitutes spaces with hyphens. This is
+  # typically used for section titles and document titles to generate
+  # a cross-reference to an anchor.
+  #
+  # @param path [String] the path of the source document relative to the project root
+  # @return [String] the formatted path
+  def self.targetify(path)
+    path.downcase.gsub(/\s/, '-')
+  end
+
+  # Recursively globs all files with the .adoc extension and matches cross-references, 
+  # section titles and anchors. Cross-references to Requirements are excluded and handled 
+  # in their own processor as they are a special case (i.e., there is no built-in support).
+  #
+  # @return [String] the formatted path
+  def self.list_xrefs
+
+    # @todo Maybe don't do this. Find a better way to process
+    # all .adoc files before extensions are loaded.
+    adoc_files = Dir.glob('**/*.adoc')
+
+    # Make some arrays available
+    titles = []
+    anchors = []
+    xrefs = []
+    mismatches = []
+
+    replacement = ''
+
+    adoc_files.each do |file_name|
+      lc = 0
+
+      File.read(file_name).each_line do |li|
+        lc += 1
+
+        # @note Matches all <<xrefs>> except Requirements
+        if li[/\<\<(?!Req)(.+?)\>\>/]
+
+          text = ''
+          target = ''
+          path = trim(file_name)
+          xref = li.chop.match(/\<\<(?!Req)(\S.+?)\>\>/i).captures[0].to_s
+
+          # @note Checks if the xref has display text, i.e. '<<title-1,Lovely Display Text>>'
+          if xref[/,/]
+            # @todo Use helper methods.
+            target = xref.downcase.gsub(/,.+/, '').gsub(/\s/, '-')
+            text = xref.gsub(/.+,/, '').lstrip!
+            xref = xref.sub(/,.+/, '')
+            path = file_name
+          else
+            # @todo Use helper methods.
+            target = xref.downcase.gsub(/\s/, '-')
+            text = xref
+          end
+
+          item = [xref, path, file_name, text, target]
+          xrefs.push item
+
+        # Match .Titles and = Section Titles
+        elsif li[/(^(\.\S\w+)|^(\=+\s+?\S+.+))/]
+
+          # Add check if none found (captures nil)
+          title = li.chop.match(/(?!=+\s)(\S+.+?)$/i).captures[0]
+          title.sub(/\.(?=\w+?)/, '') if title[/\.(?=\w+?)/]
+          path = trim(file_name)
+          item = [title, path, file_name]
+          titles.push item
+
+        # Match [[anchors]]
+        elsif li[/\[\[.+?\]\]/]
+
+          # Add check if none found (captures nil)
+          anchor = li.chop.match(/(?<=\[\[).+?(?=\]\])/).to_s
+
+          if anchor[/,/]
+            anchor = anchor.match(/(?<=\[\[)(?:|[\w+?_:][\w+?:.-]*)(?=,.+?\]\])/).to_s
+            text = anchor.sub(/.+?,/, '')
+            text = text.sub(/\]\]$/, '')
+          end
+
+          path = trim(file_name)
+          item = [anchor, path, file_name, text]
+          # for the moment, just handle anchors similar to titles
+          titles.push item
+
+        end
+      end
+    end
+
+    # Run through each xref and check for matching titles
+    xrefs.each do |xref, xpath, xfile, xtext, xtarget|
+      # check xrefs against titles
+      titles.each do |ttext, tpath, tfile, _tdisp|
+
+        next unless ttext == xref
+        tpath = 'index' if tpath.to_s.empty?
+        # If the paths are not the same (xref and title not the same document) do the following
+        next unless tpath != xpath
+
+        xtform = targetify(xtarget)
+        detail = [xref, xtarget, xtext, xpath, xfile, ttext, tpath, tfile, xtform]
+        mismatches.push detail
+      end
+    end
+  end
+end

data/lib/jekyll_aspec/version.rb

@@ -1,3 +1,6 @@
+# Use this to set global versioning for the RubyGem
 module JekyllAspec
-  VERSION = "1.0.0-alpha"
+  # After updating the version, publishing can be done by running 
+  # rake release in the project root
+  VERSION = "1.0.0"
 end

data/lib/jekyll_aspec.rb

@@ -6,12 +6,14 @@ require_relative "extensions/inline_repo_macro"
 require_relative "extensions/inline_task_macro"
 require_relative "extensions/req_preprocessor"
 require_relative "extensions/req_refs"
-require_relative "extensions/requirement_appendix"
-require_relative "extensions/requirement_block"
+require_relative "extensions/requirement_block_macro"
 require_relative "extensions/todo_block"
 
 require "jekyll_aspec/version"
 
+# Load Asciidoctor extensions
 Extensions.register do
   block TodoBlock
+  block RequirementBlock
+  block_macro RequirementsBlockMacro
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_aspec
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.alpha
+  version: 1.0.0
 platform: ruby
 authors:
 - bsmith-n4
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-25 00:00:00.000000000 Z
+date: 2017-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,7 +66,11 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.0
-description: 
+description: "This plugin is a group of Asciidoctor extensions that perform directory
+  walking, \n                          resolving the location of titles and anchors
+  in all adoc files so that inter-document\n                          cross-references
+  in a Jekyll project are resolved automatically. Also included are some \n                          custom
+  macros and blocks that are useful for techinical writing."
 email:
 - brian.smith@numberfour.eu
 executables: []
@@ -78,10 +82,13 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.md
+- README.adoc
 - Rakefile
 - bin/console
 - bin/setup
+- docs/inline-task.adoc
+- docs/requirement-block.adoc
+- docs/todo-block.adoc
 - jekyll_aspec.gemspec
 - lib/extensions/autoxrefs.rb
 - lib/extensions/html_postprocessor.rb
@@ -92,11 +99,13 @@ files:
 - lib/extensions/replace_regex.rb
 - lib/extensions/req_preprocessor.rb
 - lib/extensions/req_refs.rb
-- lib/extensions/requirement_appendix.rb
 - lib/extensions/requirement_block.rb
+- lib/extensions/requirement_block_macro.rb
 - lib/extensions/todo_block.rb
 - lib/extensions/utils/block.rb
 - lib/extensions/utils/labels.rb
+- lib/extensions/utils/req_macro_walker.rb
+- lib/extensions/utils/xref_helper.rb
 - lib/jekyll_aspec.rb
 - lib/jekyll_aspec/version.rb
 homepage: https://github.com/bsmith-n4/jekyll_aspec
@@ -111,12 +120,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.12

data/README.md

@@ -1,30 +0,0 @@
-# Jekyll Aspec
-
-[![Build Status](https://travis-ci.org/bsmith-n4/jekyll_aspec.svg?branch=master)](https://travis-ci.org/bsmith-n4/jekyll_aspec)
-
-A selection of Asciidoctor extensions designed to used with Jekyll. 
-
-These extensions add custom blocks for Requirements, Definitions and inter-document auto-linking functionality for these blocks.
-
-## Installation
-
-Add `jekyll_aspec` to your Jekyll Gemfile:
-
-```ruby
-group :jekyll_plugins do
-  gem 'jekyll-asciidoc'
-  gem 'jekyll_aspec'
-end
-```
-
-Or install it yourself as:
-
-    $ gem install jekyll_aspec
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/bsmith-n4/jekyll_aspec.
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/extensions/requirement_appendix.rb

@@ -1,115 +0,0 @@
-require 'asciidoctor'
-require 'asciidoctor/extensions'
-
-exts = "(\.adoc|\.md|\.html)"
-docsdir = '_docs'
-
-title = nil
-chapter = nil
-doctitle = nil
-
-reqs = []
-rows = []
-# For commented requirements
-coms = []
-
-# For includes
-inc_reqs = []
-incs = []
-
-CommentBlockRx = %r(^\/{4,}$)
-CommentLineRx = %r{^//(?=[^/]|$)}
-
-def trim(s)
-  s.gsub!(/_docs\//, '')
-  s.gsub!(/(\.adoc|\.md|\.html)/, '')
-end
-
-adoc_files = Dir.glob('**/*.adoc')
-adoc_files.each do |f|
-  inc = false
-  commented = false
-
-  File.read(f).each_line do |li|
-    incommentblock ^= true if li[CommentBlockRx]
-    commented = true if li[CommentLineRx]
-    inc = true if li[/published: false/]
-
-    doctitle = /(?<=title:\s).+/.match(li) if li[/^title:\s+\w.+/]
-    chapter = /(?<=chapter:\s).+/.match(li) if li[/^chapter:\s+\w.+/]
-
-    if li[/\[\s*req\s*,\s*id\s*=\s*\w+-?[0-9]+\s*,.*/]
-      title.sub!(/^\./, '')
-      req = [li.chop, f, title, chapter, doctitle]
-
-      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
-      path = inc_file.sub(/^#{docsdir}\//, '')
-      path = path.sub(/#{exts}/, '')
-      parent = f
-      item = [inc_file, path, parent]
-      incs.push item
-
-    end
-    title = li
-  end
-end
-
-# Sort included reqs and correct the path to the parent (including doc)
-# Push this back into 'normal' requirements array for regular processing
-inc_reqs.each do |l, f, title, chapter, doctitle|
-  incs.each do |incfile, _incpath, parent|
-    if f == incfile
-      item = [l, parent, title, chapter, doctitle]
-      reqs.push item
-    end
-  end
-end
-
-reqs.uniq!
-
-i = 0
-reqs.each do |req, f, title, chapter, doctitle|
-  i += 1
-
-  id = /[^,]*\s*id\s*=\s*(\w+-?[0-9]+)\s*,.*/.match(req)[1]
-  version = /(?<=version=)\d+/.match(req)
-
-  f.gsub!(/^_docs\//, '')
-  f.gsub!(/.adoc$/, '')
-
-  link = "#{f}/index##{id}"
-  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>#{id}</td><td>#{version}</td> <td>#{ref}</td> <td>#{breadcrumb}</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>Document</th>
-        </tr> </thead>
-        <tbody>
-          #{rows.join}
-        </tbody>
-        </table> </div>)
-
-      create_pass_block parent, content, {}
-    end
-  end
-end