giblish 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2e06197e632acf984fd627c5bd9ed60934a6ba4f
+  data.tar.gz: 2cafd5a3eaf191f4bcf74bb7121f6c370c8a5518
+SHA512:
+  metadata.gz: ab5f2e8b5a2e218385fbad17447cd29379a2f28cda64bcf6cf972b38c7da3a49ced8586d6bd2763b23fa05b102400d1c9a871d016621a786b52b39559983d78a
+  data.tar.gz: db3ebc6969d4abb83db8345f2201ff992bbd88ebe3f049d838fdec3c234e930348a3cc2c6a5eabd75d64374b267ef25101d9a67d65ccd10ecb9e5aecec30764e

data/.gitignore

@@ -0,0 +1,50 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in giblish.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 rillbert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.adoc

@@ -0,0 +1,67 @@
+= Giblish: Generate docs from asciidoc files in a git repo
+
+== Purpose
+giblish is used to convert a source directory tree containing AsciiDoc files to
+a destination directory tree containing the corresponding html or pdf files
+and add a handy index page for the converted files.
+
+If the source directory tree is part of a git repository, giblish can generate
+separate html/pdf trees for branches and/or tags that match a user specified
+regexp (see examples below).
+
+== Dependencies and credits
+
+Giblish is basically a convenience wrapper around the awesome asciidoctor and
+asciidoctor-pdf projects. Thank you @mojavelinux and others for making these
+brilliant tools!!
+
+== Installation
+
+ gem install giblish
+
+== Usage Examples
+
+.Get available options
+====
+ giblish -h
+====
+
+.Giblish 'hello world'
+====
+ giblish my_src_root my_dst_root
+
+The above will convert all .adoc or .ADOC files under the dir `my_src_root` to
+html and place the resulting files under the `my_dst_root` dir. An index page
+named `index.html` is generated in the `my_dst_root` dir containing links and
+some info about the converted files.
+
+The default asciidoctor css will be used in the html conversion.
+====
+
+.Using a different css
+====
+ giblish -r ./path/to/my/resources -s mylayout my_src_root my_dst_root
+
+The above will convert all .adoc or .ADOC files under the dir `my_src_root` to
+html and place the resulting files under the `my_dst_root` dir. An index page
+named `index.html` is generated in the `my_dst_root` dir containing links and
+some info about the converted files.
+
+A css named mylayout.css must be found in the dir
+`<working_dir/path/to/my/resources/css`. The resulting html files will link
+to this css. Fonts and images used from the css must be found under
+`<working_dir/path/to/my/resources/fonts` and
+`<working_dir/path/to/my/resources/images` respectively.
+====
+
+.Generate docs from multiple git branches
+====
+ giblish -g "feature" my_src_root my_dst_root
+
+The above will check-out all branches matching the regexp "feature" and convert
+the .adoc or .ADOC files under the dir `my_src_root` to html and place the
+resulting files under the `my_dst_root/<branch_name>` dir. An index page named
+`index.html` is generated in each `my_dst_root/<branch_name` dir containing links and
+some info about the converted files. A summary page containing links to all
+branches will be generated directly in the `my_dst_root` dir.
+====

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+# task :default => :spec
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "giblish"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/giblish

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+#
+#
+
+require "giblish"
+
+Giblish.application.run

data/lib/giblish.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require_relative "giblish/version"
+require_relative "giblish/utils"
+require_relative "giblish/core"
+require_relative "giblish/buildindex"
+require_relative "giblish/cmdline"
+require_relative "giblish/pathtree"
+require_relative "giblish/application"
+
+module Giblish
+  class << self
+
+    def application
+      @application ||= Giblish::Application.new
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Giblish.application.run
+end

data/lib/giblish/application.rb

@@ -0,0 +1,34 @@
+
+require_relative "cmdline"
+require_relative "core"
+require_relative "utils"
+
+module Giblish
+  class Application
+    def run
+      # setup logging
+      Giblog.setup
+
+      # Parse cmd line
+      cmdline = CmdLineParser.new ARGV
+
+      Giblog.logger.debug { "cmd line args: #{cmdline.args.to_s}" }
+
+      # Convert using given args
+      begin
+        if cmdline.args[:gitRepoRoot]
+          Giblog.logger.info {"User asked to parse a git repo"}
+          GitRepoParser.new cmdline.args
+        else
+          tc = TreeConverter.new cmdline.args
+          tc.walk_dirs
+        end
+      rescue Exception => e
+        puts "Error: #{e.message}"
+        puts "\n"
+        puts "Backtrace:\n\t#{e.backtrace.join("\n\t")}"
+        puts cmdline.usage
+      end
+    end
+  end
+end

data/lib/giblish/buildindex.rb

@@ -0,0 +1,454 @@
+#!/usr/bin/env ruby
+#
+
+require "pathname"
+require "git"
+require_relative "cmdline"
+require_relative "pathtree"
+
+# Container class for bundling together the data we cache for
+# each asciidoc file we come across
+class DocInfo
+  # Cache git info
+  class DocHistory
+    attr_accessor :date
+    attr_accessor :author
+    attr_accessor :message
+  end
+
+  attr_accessor :converted
+  attr_accessor :title
+  attr_accessor :doc_id
+  attr_accessor :purpose_str
+  attr_accessor :status
+  attr_accessor :relPath
+  attr_accessor :srcFile
+  attr_accessor :history
+  attr_accessor :error_msg
+  attr_accessor :stderr
+
+  def initialize
+    @history = []
+  end
+
+  def to_s
+    "DocInfo: title: #{@title} srcFile: #{@srcFile}"
+  end
+end
+
+# Base class with common functionality for all index builders
+class BasicIndexBuilder
+  # set up the basic index building info
+  def initialize(path_manager)
+    @paths = path_manager
+    @added_docs = []
+    @src_str = ""
+  end
+
+  # creates a DocInfo instance, fills it with basic info and
+  # returns the filled in instance so that derived implementations can
+  # add more data
+  def add_doc(adoc, adoc_stderr)
+    Giblog.logger.debug { "Adding adoc: #{adoc} Asciidoctor stderr: #{adoc_stderr}" }
+
+    info = DocInfo.new
+    info.converted = true
+    info.stderr = adoc_stderr
+
+    # Get the doc id if it exists
+    info.doc_id = adoc.attributes["docid"]
+
+    # Get the purpose info if it exists
+    info.purpose_str = get_purpose_info adoc
+
+    # Get the relative path beneath the root dir to the doc
+    info.relPath = Pathname.new(
+      adoc.attributes["outfile"]
+    ).relative_path_from(
+      @paths.dst_root_abs
+    )
+
+    # Get the source file path and title
+    info.srcFile = adoc.attributes["docfile"]
+    info.title = adoc.doctitle
+
+    # Cache the created DocInfo
+    @added_docs << info
+    info
+  end
+
+  def add_doc_fail(filepath, exception)
+    info = DocInfo.new
+
+    # the only info we have is the source file name
+    info.converted = false
+    info.srcFile = filepath
+    info.error_msg = exception.message
+
+    # Cache the DocInfo
+    @added_docs << info
+    info
+  end
+
+  def index_source
+    <<~DOC_STR
+      #{generate_header}
+      #{generate_tree}
+      #{generate_details}
+      #{generate_footer}
+    DOC_STR
+  end
+
+  protected
+
+  def generate_header
+    t = Time.now
+    <<~DOC_HEADER
+      = Document index
+      from #{@paths.src_root_abs}
+
+      Generated by Giblish at::
+
+      #{t.strftime('%Y-%m-%d %H:%M')}
+
+    DOC_HEADER
+  end
+
+  def generate_footer
+    ""
+  end
+
+  private
+
+  def get_purpose_info(adoc)
+    # Get the 'Purpose' section if it exists
+    purpose_str = ""
+    adoc.blocks.each do |section|
+      next unless section.is_a?(Asciidoctor::Section) &&
+                  (section.level == 1) &&
+                  (section.name =~ /^Purpose$/)
+      purpose_str = "Purpose::\n\n"
+      section.blocks.each do |bb|
+        next unless bb.is_a?(Asciidoctor::Block)
+        purpose_str << "#{bb.source}\n+\n"
+      end
+    end
+    purpose_str
+  end
+
+  def generate_conversion_info(d)
+    return "" if d.stderr.empty?
+    # extract conversion warnings from asciddoctor std err
+    conv_warnings = d.stderr.gsub("asciidoctor:", "\n * asciidoctor:")
+    Giblog.logger.warn { "Conversion warnings: #{conv_warnings}" }
+
+    # assemble info to index page
+    <<~CONV_INFO
+      Conversion info::
+
+      #{conv_warnings}
+    CONV_INFO
+  end
+
+  # Private: Return adoc elements for displaying a clickable title
+  # and a 'details' ref that points to a section that uses the title as an id.
+  #
+  # Returns [ clickableTitleStr, clickableDetailsStr ]
+  def format_title_and_ref(doc_info)
+    unless doc_info.title
+      @nof_missing_titles += 1
+      doc_info.title = "NO TITLE FOUND (#{@nof_missing_titles}) !"
+    end
+    return "<<#{doc_info.relPath}#,#{doc_info.title}>>",
+    "<<#{Giblish.to_valid_id(doc_info.title)},details>>\n"
+  end
+
+  # Generate an adoc string that will display as
+  # DocTitle         (warn)  details
+  # Where the DocTitle and details are links to the doc itself and a section
+  # identified with the doc's title respectively.
+  def tree_entry_converted(prefix_str, doc_info)
+    # Get the elements of the entry
+    doc_title, doc_details = format_title_and_ref doc_info
+    warning_label = doc_info.stderr.empty? ? "" : "(warn)"
+
+    # Calculate padding to get (warn) and details aligned between entries
+    padding = 80
+    [doc_info.title, prefix_str, warning_label].each { |p| padding -= p.length }
+    padding = 0 unless padding.positive?
+    "#{prefix_str} #{doc_title}#{' ' * padding}#{warning_label} #{doc_details}"
+  end
+
+  def tree_entry_string(level, node)
+    # indent 2 * level
+    prefix_str = "  " * (level + 1)
+
+    # return only name for directories
+    return "#{prefix_str} #{node.name}\n" unless node.leaf?
+
+    # return links to content and details for files
+    d = node.data
+    if d.converted
+      tree_entry_converted prefix_str, d
+    else
+      # no converted file exists, show what we know
+      "#{prefix_str} FAIL: #{d.srcFile}      <<#{d.srcFile},details>>\n"
+    end
+  end
+
+  def generate_tree
+    # build up tree of paths
+    root = PathTree.new
+    @added_docs.each do |d|
+      root.add_path(d.relPath.to_s, d)
+    end
+
+    # output tree intro
+    tree_string = <<~DOC_HEADER
+      == Document Overview
+
+      _Click on the title to open the document or on `details` to see more
+      info about the document. A `(warn)` label indicates that there were
+      warnings while converting the document._
+
+      [subs=\"normal\"]
+      ----
+    DOC_HEADER
+
+    # generate each tree entry string
+    root.traverse_top_down do |level, node|
+      tree_string << tree_entry_string(level, node)
+    end
+
+    # generate the tree footer
+    tree_string << "\n----\n"
+  end
+
+  # Derived classes can override this with useful info
+  def generate_history_info(_d)
+    ""
+  end
+
+  def generate_detail_fail(d)
+    <<~FAIL_INFO
+      === #{d.srcFile}
+
+      Source file::
+
+      #{d.srcFile}
+
+      Error detail::
+      #{d.stderr}
+
+      ''''
+
+    FAIL_INFO
+  end
+
+  def generate_detail(d)
+    # Generate detail info
+    <<~DETAIL_SRC
+      [[#{Giblish.to_valid_id(d.title)}]]
+      === #{d.title}
+
+      #{d.purpose_str}
+
+      #{generate_conversion_info d}
+
+      Source file::
+      #{d.srcFile}
+
+      #{generate_history_info d}
+
+      ''''
+
+    DETAIL_SRC
+  end
+
+  def generate_details
+    root = PathTree.new
+    @added_docs.each do |d|
+      root.add_path(d.relPath.to_s, d)
+    end
+
+    details_str = "== Document details\n\n"
+
+    root.traverse_top_down do |_level, node|
+      details_str << if node.leaf?
+                       d = node.data
+                       if d.converted
+                         generate_detail(d)
+                       else
+                         generate_detail_fail(d)
+                       end
+                     else
+                       ""
+                     end
+    end
+    details_str
+  end
+end
+
+# A simple index generator that shows a table with the generated documents
+class SimpleIndexBuilder < BasicIndexBuilder
+  def initialize(path_manager)
+    super path_manager
+  end
+
+  def add_doc(adoc, adoc_stderr)
+    super(adoc, adoc_stderr)
+  end
+end
+
+# Builds an index of the generated documents and includes some git metadata
+# repository
+class GitRepoIndexBuilder < BasicIndexBuilder
+  def initialize(path_manager, git_repo_root)
+    super path_manager
+    @git_repo_root = git_repo_root
+
+    # no repo root given...
+    return unless @git_repo_root
+
+    begin
+      # Make sure that we can "talk" to git if user feeds us
+      # a git repo root
+      @git_repo = Git.open(@git_repo_root)
+
+      # initialize state variables
+      @nof_missing_titles = 0
+    rescue Exception => e
+      Giblog.logger.error { "No git repo! exception: #{e.message}" }
+    end
+  end
+
+  def add_doc(adoc, adoc_stderr)
+    info = super(adoc, adoc_stderr)
+
+    # Redefine the srcFile to mean the relative path to the git repo root
+    info.srcFile = Pathname.new(info.srcFile).relative_path_from(@git_repo_root).to_s
+
+    # Get the commit history of the doc
+    @git_repo.log(50).object("*#{info.srcFile}").each do |l|
+      h = DocInfo::DocHistory.new
+      h.date = l.date
+      h.message = l.message
+      h.author = l.author.name
+      info.history << h
+    end
+  end
+
+  protected
+
+  def generate_header
+    t = Time.now
+    <<~DOC_HEADER
+      = Document index
+      #{@git_repo.current_branch}
+
+      Generated by Giblish at::
+
+      #{t.strftime('%Y-%m-%d %H:%M')}
+
+    DOC_HEADER
+  end
+
+  def generate_history_info(d)
+    str = <<~HISTORY_HEADER
+      File history::
+
+      [cols=\"2,3,8\",options=\"header\"]
+      |===
+      |Date |Author |Message
+    HISTORY_HEADER
+
+    # Generate table rows of history information
+    d.history.each do |h|
+      str << <<~HISTORY_ROW
+        |#{h.date.strftime('%Y-%m-%d')}
+        |#{h.author}
+        |#{h.message}
+
+      HISTORY_ROW
+    end
+    str << "|===\n\n"
+  end
+end
+
+# Builds an index page with a summary of what branches have
+# been generated
+class GitSummaryIndexBuilder
+  def initialize(repo)
+    @branches = []
+    @tags = []
+    @repo_url = repo.remote.url
+  end
+
+  def add_branch(b)
+    @branches << b
+  end
+
+  def add_tag(t)
+    @tags << t
+  end
+
+  def index_source
+    <<~ADOC_SRC
+      #{generate_header}
+      #{generate_branch_info}
+      #{generate_tag_info}
+      #{generate_footer}
+    ADOC_SRC
+  end
+
+  private
+
+  def generate_header
+    t = Time.now
+    <<~DOC_HEADER
+      = Document repository
+      From #{@repo_url}
+
+      Generated by Giblish at::
+
+      #{t.strftime('%Y-%m-%d %H:%M')}
+
+    DOC_HEADER
+  end
+
+  def generate_footer
+    ""
+  end
+
+  def generate_branch_info
+    return "" if @branches.empty?
+
+    # get the branch-unique dst-dir
+    str = <<~BRANCH_INFO
+      == Branches
+
+    BRANCH_INFO
+
+    @branches.each do |b|
+      dirname = b.name.tr "/", "_"
+      str << " * link:#{dirname}/index.html[#{b.name}]\n"
+    end
+    str
+  end
+
+  def generate_tag_info
+    return "" if @tags.empty?
+
+    # get the branch-unique dst-dir
+    str = <<~TAG_INFO
+      == Tags
+
+    TAG_INFO
+
+    @tags.each do |t|
+      dirname = t.name.tr "/", "_"
+      str << " * link:#{dirname}/index.html[#{t.name}]\n"
+    end
+    str
+  end
+end