Class: Giblish::DocConverter

Inherits:
Object
  • Object
show all
Defined in:
lib/giblish/docconverter.rb

Overview

Base class for document converters. It contains a hash of conversion options used by derived classes

Direct Known Subclasses

HtmlConverter, PdfConverter

Constant Summary collapse

COMMON_CONVERTER_OPTS =

a common set of converter options used for all output formats

{
  safe: Asciidoctor::SafeMode::UNSAFE,
  header_footer: true,
  mkdirs: true
}.freeze
DEFAULT_ATTRIBUTES =

the giblish attribute defaults used if nothing else is required by the user

{
  "source-highlighter" => "rouge",
  "xrefstyle" => "short"
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(paths, deployment_info, options) ⇒ DocConverter

Returns a new instance of DocConverter.



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/giblish/docconverter.rb', line 32

def initialize(paths, deployment_info, options)
  @paths = paths
  @deployment_info = deployment_info
  @user_style = options[:userStyle]
  @converter_options = COMMON_CONVERTER_OPTS.dup

  # use the default options and override them with options set by
  # the user if applicable
  @converter_options[:attributes] = DEFAULT_ATTRIBUTES.dup
  @converter_options[:attributes].merge!(options[:attributes]) unless options[:attributes].nil?
  @converter_options[:backend] = options[:backend]

  # give derived classes the opportunity to add options and attributes
  add_backend_options(@converter_options)
  add_backend_attributes(@converter_options[:attributes])
end

Instance Attribute Details

#converter_options ⇒ Object (readonly)

setup common options that are used regardless of the specific output format used



27
28
29
 
# File 'lib/giblish/docconverter.rb', line 27

def converter_options
  @converter_options
end

#paths ⇒ Object

the path manager used by this converter



30
31
32
 
# File 'lib/giblish/docconverter.rb', line 30

def paths
  @paths
end

Instance Method Details

#convert(filepath, logger: nil) ⇒ Object

Public: Convert one single adoc file using the specific conversion options.

filepath - a pathname with the absolute path to the input file to convert

Returns: The resulting Asciidoctor::Document object

Raises:

  • (ArgumentError) 


55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/giblish/docconverter.rb', line 55

def convert(filepath, logger: nil)
  raise ArgumentError, "Trying to invoke convert with non-pathname!" unless filepath.is_a?(Pathname)

  Giblog.logger.info { "Processing: #{filepath}" }

  # update the relevant options for each specific document
  set_common_doc_specific_options(filepath, logger)

  # give derived classes the opportunity to set doc specific attributes
  add_doc_specific_attributes(filepath, true, @converter_options[:attributes])

  Giblog.logger.debug { "converter_options: #{@converter_options}" }

  # do the actual conversion
  doc = Asciidoctor.convert_file filepath, @converter_options

  # bail out if asciidoctor failed to convert the doc
  if logger&.max_severity && logger.max_severity > Logger::Severity::WARN
    raise "Failed to convert the file #{filepath}"
  end

  doc
end

#convert_str(src_str, dst_dir, basename, logger: nil) ⇒ Object

converts the supplied string to the file dst_dir/basename.<backend-ext>

the supplied string must pass asciidoctor without any error to stderr, otherwise, nothing will be written to disk. Returns: whether any errors occured during conversion (true) or not (false).



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/giblish/docconverter.rb', line 87

def convert_str(src_str, dst_dir, basename, logger: nil)
  index_opts = @converter_options.dup

  # use the same options as when converting all docs
  # in the tree but make sure we don't write to file
  # by trial and error, the following dirs seem to be
  # necessary to change
  index_opts[:to_dir] = dst_dir.to_s
  index_opts[:base_dir] = dst_dir.to_s
  index_opts.delete_if { |k, _v| %i[to_file].include? k }

  # give derived classes the opportunity to set doc specific attributes
  index_filepath = dst_dir + "#{basename}.#{index_opts[:fileext]}"
  add_doc_specific_attributes(index_filepath, false, index_opts[:attributes])

  # load and convert the document using the converter options
  begin
    conv_error = false
    # set a specific logger instance to-be-used by asciidoctor
    index_opts[:logger] = logger unless logger.nil?
    doc = Asciidoctor.load src_str, index_opts
    output = doc.convert index_opts

    if logger&.max_severity && logger.max_severity > Logger::Severity::WARN
      raise "Failed to convert string to asciidoc!! "\
            "Will _not_ generate #{index_filepath}"
    end

    # write the converted document to an index file located at the
    # destination root
    doc.write output, index_filepath.to_s
  rescue StandardError => e
    puts e.backtrace
    Giblog.logger.error(e)
    conv_error = true
  end

  conv_error
end