prawn-manual_builder 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d4873e82c2906833aa5480dcd264453e839b62a67254e8bd6c43c361430be8b
-  data.tar.gz: 4958041c344dcb46dae8142b07872995d3e649bd9e5bc94befc7f476a5bd45b3
+  metadata.gz: cfd5c78fb9db44ad2832807a23ee19813304f3e2d484744a713d2a60eee651ec
+  data.tar.gz: 9863d4dd0e1767293ff0f32bd41496a85db40b9289dfbb1763f734cb2ffbe530
 SHA512:
-  metadata.gz: c29745b0d6d5e43c81907857eb695017cce649d30b9905e0baffe52cf8385fa4073bdaad5021c936f57b87196cf9288659351ef4f9e63268b2f35c0d364f8e86
-  data.tar.gz: d1a4eff4362d6e9a4fbe5a644cbf385c8aaf66d56baf2eb0a1e3cc3d1330f1ec791125906cb2f62dcecf616394861b066cf0838e76f3e95ac66d9318cd6724c9
+  metadata.gz: b3e5ef3376d39d2ab8f11862aaeb4c0dca74d46cd774ae34301227b26b4ea27ee3e3657c1ec2aacbcedd6d0e1e33be5c6ebce4aa71014ce41ff596638a0d8354
+  data.tar.gz: 43965e339ab569298c301cf484547d6afa47953158372b94ee45b224b58a3874ed57f35ab19991d4c6eb8cd19b71e92eab4e8f61bf8f2fcfe5db34c22acc79fd

checksums.yaml.gz.sig

@@ -0,0 +1,2 @@
+Y*6_�ޏ��_Y-˫�: +�@�i�T�~��s������<6"�
 ����ɟQ �T�NN����
+K�$�<��4h���~����5�Ek�C�NE_�H�+b�悰�}��d;L�+ʤ�?����:��.�vjnY�*Nfn)�#/j�@�

data/lib/prawn/manual_builder/chapter.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require 'prism'
+require_relative 'part'
+require_relative 'text_renderer'
+require_relative "syntax_highlight"
+
+module Prawn
+  module ManualBuilder
+    class Chapter < Part
+      def initialize(&block)
+        super
+
+        if block
+          instance_eval(&block)
+        else
+          warn "Chapter defined in #{__FILE__} has no content"
+        end
+
+        self.auto_render = true
+        at_exit do
+          if self.auto_render
+            execute_example
+          end
+        end
+      end
+
+      # Chapter DSL
+      def title(title = NOT_SET)
+        if title == NOT_SET
+          @title
+        else
+          @title = title
+        end
+      end
+
+      def text(&block)
+        if !block_given?
+          @text
+        else
+          @text = block
+        end
+      end
+
+      def example(source = NOT_SET, axes: false, new_page: false, eval: true, standalone: false, &block)
+        if source == NOT_SET && !block_given?
+          @example
+        elsif source != NOT_SET && block_given?
+          raise ArgumentError, "Example can't be specified both as a block and as a string"
+        else
+          if source != NOT_SET
+            @example = source
+          else
+            @example = block
+          end
+          @example_axes = axes
+          @eval_example = eval
+          @standalone_example = standalone
+          @new_page_example = new_page
+        end
+      end
+
+      def eval_example?
+        @eval_example
+      end
+
+      def standalone_example?
+        @standalone_example
+      end
+
+      def new_page_example?
+        @new_page_example
+      end
+
+      def example_axes?
+        @example_axes
+      end
+
+      def render(doc)
+        doc.start_new_page(margin: PAGE_MARGIN)
+        @page_number = doc.page_number
+
+        chapter_header(doc)
+
+        inner_box(doc) do
+          TextRenderer.new(doc, &text).render
+        end
+
+        example_source(doc)
+
+        if eval_example? && !standalone_example?
+          eval_example(doc)
+        end
+
+        unless eval_example?
+          standalone_example(doc)
+        end
+      end
+
+      def to_s
+        super[-2, 0] = " path: #{path}"
+      end
+
+      private
+
+      def example_source_code
+        case example
+        when Proc
+          block_source_line = example.source_location.last
+          source = File.read(path)
+          parse_result = Prism.parse(source)
+
+          block =
+            Prism::Pattern.new("CallNode[name: :example, block: BlockNode]")
+              .scan(parse_result.value)
+              .find { |node| node.block.location.start_line == block_source_line }
+              &.block
+
+          return '' unless block
+
+          source.byteslice(block.opening_loc.end_offset, block.closing_loc.start_offset - block.opening_loc.end_offset)
+            .then { _1.gsub(/^#{_1.scan(/^[ \t]*(?=\S)/).min}/, '') } # Remove indentation
+        when String
+          example
+        else
+          ''
+        end
+          .sub(/(?<=\A)([ \t]*\r?\n)*/, '') # Remove empty lines at the beginning
+          .rstrip # Remove trailing whitespace
+      end
+
+      def chapter_header(doc)
+        raise "Title is not set" unless title
+
+        header_options = {
+          leading: 6,
+          final_gap: false,
+        }
+        header_text = [
+          { text: title, font: HEADER_FONT, size: HEADER_FONT_SIZE, color: DARK_GRAY },
+        ]
+
+        if manual.root_path && example
+          rel_path = Pathname.new(path).relative_path_from(manual.root_path)
+
+          header_text.concat(
+            [
+              { text: "\n" },
+              { text: "#{rel_path.dirname}/", color: BROWN, font: 'Iosevka', size: HEADER_FONT_SIZE * 0.75 },
+              { text: "#{rel_path.basename}", color: ORANGE, font: 'Iosevka', size: HEADER_FONT_SIZE * 0.75 },
+            ]
+          )
+        end
+
+        TextRenderer.new(doc) do
+          header_with_bg(header_text, header_options)
+        end.render
+      end
+
+      def example_source(doc)
+        return if example_source_code.empty?
+
+        doc.font(CODE_FONT, size: CODE_FONT_SIZE) do
+          colored_box(doc, SyntaxHighlight.new(example_source_code).to_prawn, fill_color: DARK_GRAY)
+        end
+      end
+
+      def eval_example(doc)
+        old_new_page_callback = doc.new_page_callback
+        crossed_page = false
+        doc.new_page_callback = lambda do |doc|
+          # Reset bounding box on new page
+          doc.bounds = Prawn::Document::BoundingBox.new(
+            doc,
+            nil,
+            [0, doc.page.dimensions[3]],
+            width: doc.page.dimensions[2],
+            height: doc.page.dimensions[3]
+          )
+          setup_example_area(doc)
+          crossed_page = true
+        end
+
+        preserving_doc_settings(doc) do
+          doc.save_graphics_state do
+            doc.bounding_box(
+              [-doc.bounds.absolute_left, doc.cursor],
+              width: doc.page.dimensions[2],
+              height: doc.y
+            ) do
+              doc.start_new_page if new_page_example?
+              setup_example_area(doc) unless crossed_page
+
+              begin
+                if example.is_a?(Proc)
+                  doc.instance_eval(&example)
+                else
+                  doc.instance_eval(example, path)
+                end
+              rescue => e
+                puts "Error evaluating example: #{e.message}"
+                puts
+                puts "---- Source: ----"
+                puts
+                puts example
+                puts
+                puts "---- Backtrace: ----"
+                puts e.backtrace
+              end
+            end
+          end
+        end
+      ensure
+        doc.new_page_callback = old_new_page_callback
+      end
+
+      def setup_example_area(doc)
+        doc.save_graphics_state do
+          line_width = PAGE_MARGIN
+          text_size = PAGE_MARGIN * 0.6
+          doc.stroke_color(GRAY)
+          doc.line_width(line_width)
+
+          doc.stroke_rectangle([line_width / 2, doc.bounds.top - line_width / 2], doc.bounds.width - line_width, doc.bounds.height - line_width)
+
+          # We're reseting fonts for the example so we have to add it again
+          example_title_font = '_ManualExampleTitle'
+          doc.font_families.update(
+            example_title_font => {
+              normal: "#{Prawn::ManualBuilder::DATADIR}/fonts/DejaVuSans-Bold.ttf",
+              bold: "#{Prawn::ManualBuilder::DATADIR}/fonts/DejaVuSans-Bold.ttf",
+            })
+          example_title = 'Example Output'
+          text = [{text: example_title, font: example_title_font, size: text_size, styles: [:bold], color: 'ffffff'}]
+          h = doc.height_of_formatted(text, { final_gap: false })
+
+          doc.bounding_box(
+            [line_width, doc.bounds.top - (line_width - h) / 2 * 1.25],
+            width: doc.bounds.width - line_width * 2
+          ) do
+            doc.formatted_text(text, align: :right)
+          end
+        end
+
+        doc.bounds = Prawn::Document::BoundingBox.new(
+          doc,
+          doc.bounds,
+          [PAGE_MARGIN, doc.bounds.top - PAGE_MARGIN],
+          width: doc.bounds.width - PAGE_MARGIN * 2,
+          height: doc.bounds.height - PAGE_MARGIN * 2
+          )
+        doc.move_cursor_to(doc.bounds.height)
+
+        doc.stroke_axis if example_axes?
+      end
+
+      # Used to generate the url for the example files
+      MANUAL_URL = "https://github.com/prawnpdf/prawn/tree/master/manual"
+
+
+      # Renders a box with the link for the example file
+      def standalone_example(doc)
+        url = "#{MANUAL_URL}/#{Pathname(path).relative_path_from(manual.root_path)}"
+
+        reason = [
+          { text: "This code snippet was not evaluated inline. "\
+                  "You may see its output by running the "\
+                  "example file located here:\n",
+            color: DARK_GRAY, font: 'DejaVu', size: 11 },
+          { text: url.gsub('/', "/#{Prawn::Text::ZWSP}"), color: BLUE, link: url, font: 'DejaVu', size: 11 }
+        ]
+
+        colored_box(
+          doc, reason,
+          fill_color: LIGHT_GOLD,
+          stroke_color: DARK_GOLD,
+          leading: LEADING * 3
+        )
+      end
+
+      def execute_example
+        if standalone_example?
+          if self.example.is_a?(String)
+            eval(example, TOPLEVEL_BINDING)
+          else
+            Object.new.instance_eval(&example)
+          end
+        else
+          Prawn::Document.generate("example.pdf") do |doc|
+            if self.example.is_a?(String)
+              doc.instance_eval(example, path)
+            else
+              doc.instance_eval(&example)
+            end
+          end
+        end
+      end
+
+      def preserving_doc_settings(doc)
+        old_settings = {
+          font: doc.instance_variable_get(:@font),
+          font_size: doc.instance_variable_get(:@font_size),
+          leading: doc.default_leading,
+          text_direction: doc.text_direction,
+          line_width: doc.line_width,
+          cap_style: doc.cap_style,
+          join_style: doc.join_style,
+          fill_color: doc.fill_color,
+          stroke_color: doc.stroke_color,
+          font_families: doc.font_families.dup,
+        }
+        doc.instance_variable_set(:@font_families, nil)
+        doc.font('Helvetica', size: 12)
+
+        yield
+      ensure
+        doc.font_families.replace(old_settings[:font_families])
+        doc.set_font(old_settings[:font], size: old_settings[:font_size])
+        doc.default_leading = old_settings[:leading]
+        doc.text_direction = old_settings[:text_direction]
+        doc.line_width = old_settings[:line_width]
+        doc.cap_style = old_settings[:cap_style]
+        doc.join_style = old_settings[:join_style]
+        doc.fill_color(old_settings[:fill_color])
+        doc.stroke_color(old_settings[:stroke_color])
+      end
+    end
+  end
+end

data/lib/prawn/manual_builder/manual.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'prawn'
+
+require_relative 'part'
+require_relative 'section'
+require_relative 'peritext'
+require_relative 'chapter'
+
+module Prawn
+  module ManualBuilder
+    class Manual
+      def initialize(root_path, document_options = {}, &block)
+        @root_path = Pathname(root_path)
+        @document_options = document_options
+        @content = []
+        @container = self
+        instance_eval(&block) if block
+      end
+
+      attr_reader :root_path, :content
+
+      def generate(filename = nil)
+        doc = Prawn::Document.new({ skip_page_creation: true, margin: PAGE_MARGIN }.merge(@document_options)) do
+          jigmo_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/Jigmo.ttf"
+          jigmo2_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/Jigmo2.ttf"
+          jigmo3_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/Jigmo3.ttf"
+          dejavu_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/DejaVuSans.ttf"
+          dejavu_bold_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/DejaVuSans-Bold.ttf"
+          dejavu_italic_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/DejaVuSans-Oblique.ttf"
+          dejavu_bold_italic_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/DejaVuSans-BoldOblique.ttf"
+          iosevka_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/iosevka-po-regular.ttf"
+          iosevka_bold_file = "#{Prawn::ManualBuilder::DATADIR}/fonts/iosevka-po-bold.ttf"
+          font_families.update(
+            'Jigmo' => { normal: jigmo_file },
+            'Jigmo2' => { normal: jigmo2_file },
+            'Jigmo3' => { normal: jigmo3_file },
+            'DejaVu' => {
+              normal: dejavu_file,
+              bold: dejavu_bold_file,
+              italic: dejavu_italic_file,
+              bold_italic: dejavu_bold_italic_file,
+            },
+            'Iosevka' => {
+              normal: iosevka_file,
+              bold: iosevka_bold_file,
+            }
+          )
+
+          class << self
+            attr_accessor :new_page_callback
+
+            def start_new_page(options = {})
+              super
+
+              if new_page_callback
+                new_page_callback.call(self)
+              end
+            end
+          end
+        end
+
+        render_content(doc)
+        build_outline(doc)
+        if filename
+          doc.render_file(filename)
+        else
+          doc.render
+        end
+      end
+
+      protected
+
+      attr_reader :content
+
+      private
+
+      def title(title = NOT_SET)
+        if title == NOT_SET
+          @title
+        else
+          @title = title
+        end
+      end
+
+      # Groups chapters into sections. This is primarily used to structure manual outline.
+      def section(title)
+        section = Section.new(title)
+        @container.content << section
+        parent_container = @container
+        @container = section
+        yield
+      ensure
+        @container = parent_container
+      end
+
+      # Adds manual content. Chapter usually produces some content and is added to the document outline.
+      def chapter(relative_path)
+        part = load_part(relative_path)
+        @container.content << part
+      end
+
+      def part(relative_path)
+        part = load_part(relative_path)
+        @container.content << part
+      end
+
+      def load_part(relative_path)
+        part_path = File.join(root_path, "#{relative_path}.rb")
+        if File.exist?(part_path)
+          part = eval(File.read(part_path), TOPLEVEL_BINDING, part_path)
+          if part.is_a?(Part)
+            part.auto_render = false
+            part.path = part_path
+            part.manual = self
+          else
+            raise ArgumentError, "#{relative_path} doesn't evaluate to a Part object"
+          end
+
+          part
+        else
+          raise ArgumentError, "#{relative_path} not found"
+        end
+      end
+
+      def render_content(doc)
+        content.each do |part|
+          render_part(doc, part)
+        end
+      end
+
+      def render_part(doc, part)
+        case part
+        when Section
+          part.content.each do |subpart|
+            render_part(doc, subpart)
+          end
+        when Chapter, Peritext
+          part.render(doc)
+        else
+          raise ArgumentError, "Unknown part type #{part.class}"
+        end
+      end
+
+      def build_outline(doc)
+        doc.outline.section(title) do
+          content.each do |part|
+            add_part_to_outline(doc, part)
+          end
+        end
+      end
+
+      def add_part_to_outline(doc, part)
+        case part
+        when Section
+          doc.outline.section(part.title, destination: part.page_number) do
+            part.content.each do |subpart|
+              add_part_to_outline(doc, subpart)
+            end
+          end
+        when Chapter
+          doc.outline.page(title: part.title, destination: part.page_number)
+        when Peritext
+          # Skip
+        else
+          raise ArgumentError, "Unknown part type #{part.class}"
+        end
+      end
+    end
+  end
+end

data/lib/prawn/manual_builder/part.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Prawn
+  module ManualBuilder
+    class Part
+      attr_accessor :auto_render
+      attr_accessor :manual
+      attr_accessor :path
+      attr_reader :page_number
+
+      def render(doc)
+        raise NotImplementedError
+      end
+
+      private
+
+      def colored_box(doc, box_text, options={})
+        options = {
+          fill_color: DARK_GRAY,
+          stroke_color: nil,
+          text_color: LIGHT_GRAY,
+          leading: LEADING
+        }.merge(options)
+
+        text_options = {
+          leading: options[:leading],
+          fallback_fonts: ["DejaVu", "Jigmo", "Jigmo2", "Jigmo3"]
+        }
+
+        box_height = 0
+
+        doc.bounding_box(
+          [INNER_MARGIN + RHYTHM, doc.cursor],
+          width: doc.bounds.width - (INNER_MARGIN + RHYTHM) * 2
+        ) do
+          box_height = doc.height_of_formatted(box_text, text_options)
+        end
+
+        if box_height > doc.cursor - doc.bounds.bottom
+          doc.start_new_page
+          doc.move_down(INNER_MARGIN)
+        end
+
+        doc.bounding_box(
+          [INNER_MARGIN + RHYTHM, doc.cursor],
+          width: doc.bounds.width - (INNER_MARGIN + RHYTHM) * 2
+        ) do
+          box_height = doc.height_of_formatted(box_text, text_options)
+
+          doc.fill_color(options[:fill_color])
+          doc.stroke_color(options[:stroke_color] || options[:fill_color])
+          doc.fill_and_stroke_rounded_rectangle(
+              [doc.bounds.left - RHYTHM, doc.cursor],
+              doc.bounds.left + doc.bounds.right + RHYTHM * 2,
+              box_height + RHYTHM * 2,
+              5
+          )
+          doc.fill_color(BLACK)
+          doc.stroke_color(BLACK)
+
+          doc.pad(RHYTHM) do
+            doc.formatted_text(box_text, text_options)
+          end
+        end
+
+        doc.move_down(RHYTHM * 2)
+      end
+
+      def inner_box(doc, &block)
+        doc.bounding_box(
+          [INNER_MARGIN, doc.cursor],
+          width: doc.bounds.width - INNER_MARGIN * 2,
+          &block
+        )
+      end
+    end
+  end
+end

data/lib/prawn/manual_builder/peritext.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'prism'
+require_relative 'part'
+require_relative 'text_renderer'
+
+module Prawn
+  module ManualBuilder
+    class Peritext < Part
+
+      def initialize(&block)
+        super
+
+        if block
+          instance_eval(&block)
+        else
+          warn "Peritext defined in #{__FILE__} has no content"
+        end
+      end
+
+      # DSL
+      def text(&block)
+        if !block_given?
+          @text
+        else
+          @text = block
+        end
+      end
+
+      def render(doc)
+        doc.start_new_page(margin: PAGE_MARGIN)
+        @page_number = doc.page_number
+
+        inner_box(doc) do
+          TextRenderer.new(doc, &text).render
+        end
+      end
+    end
+  end
+end

data/lib/prawn/manual_builder/section.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Prawn
+  module ManualBuilder
+    class Section
+      def initialize(title)
+        @title = title
+        @content = []
+      end
+
+      attr_reader :title, :content
+
+      def render(doc)
+        # Do nothing
+      end
+
+      def page_number
+        content.find { _1.respond_to?(:page_number) }&.page_number
+      end
+    end
+  end
+end