nexmo-oas-renderer 0.1.0

data/lib/nexmo/oas/renderer/helpers/navigation.rb

@@ -0,0 +1,66 @@
+module Nexmo
+  module OAS
+    module Renderer
+      module Helpers
+        module Navigation
+
+          HEADING_TAG_DEPTHS = {
+            'h0' => 0,
+            'h1' => 1,
+            'h2' => 2,
+            'h3' => 3,
+            'h4' => 4,
+            'h5' => 5,
+            'h6' => 6,
+          }.freeze
+
+          def navigation_from_content(content:, title: nil)
+            content = "<h0 class='injected'>#{title}</h0>\n" + content if title
+            document = build_document(content)
+
+            nodes = ['<ul class="Vlt-sidemenu Vlt-sidemenu--rounded Vlt-sidemenu--flat navigation js-navigation">']
+            last_node = nil
+
+            document.css('.reveal').remove
+
+            document.css('h0,h2,h3,h4,h5,h6').each do |heading|
+              # If it's a header within tabbed content (including Code Snippets) we don't want to treat
+              # the header as a navigation item in the sidebar
+              next unless heading.ancestors('.Vlt-tabs').empty?
+
+              # Same with callouts
+              next unless heading.ancestors('.Vlt-callout').empty?
+
+              if last_node.nil? || heading.name == last_node.name
+                # Do nothing (cleaner than adding wrapping further conditions)
+              elsif heading.name >= last_node.name # e.g. h2 -> h3
+                nodes << '<ul>'
+              else # e.g. h4 -> h2
+                (HEADING_TAG_DEPTHS[last_node.name] - HEADING_TAG_DEPTHS[heading.name]).times do
+                  nodes << '</li></ul>'
+                end
+              end
+
+              nodes << <<~HEREDOC
+                <li>
+                <a class="Vlt-sidemenu__link" href="##{heading.attributes['id']}" data-scrollspy-id="#{heading['data-id']}">
+                  #{heading.text}
+                </a>
+              HEREDOC
+              last_node = heading
+            end
+            nodes << '</li></ul>'
+            nodes.join("\n").html_safe
+          end
+
+          private
+
+          def build_document(content)
+            Nokogiri::HTML::DocumentFragment.parse(content)
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/helpers/render.rb

@@ -0,0 +1,24 @@
+module Nexmo
+  module OAS
+    module Renderer
+      module Helpers
+        module Render
+
+          def find_template(views, name, engine, &block)
+            Array(views).each do |v|
+              super(v, name, engine, &block)
+            end
+          end
+
+          def render(*args)
+            if args.length > 2
+              super
+            else
+              ApplicationController.renderer.render(*args)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/helpers/summary.rb

@@ -0,0 +1,30 @@
+module Nexmo
+  module OAS
+    module Renderer
+      module Helpers
+        module Summary
+          def normalize_summary_title(summary, operation_id)
+            # return summary early if provided
+            return summary unless summary.nil?
+
+            # If the operation ID is camelCase,
+            if operation_id.match?(/^[a-zA-Z]\w+(?:[A-Z]\w+){1,}/x)
+              # Use the rails `.underscore` method to convert someString to some_string
+              operation_id = operation_id.underscore
+            end
+
+            # Replace snake_case and kebab-case with spaces and titelize the string
+            operation_id = operation_id.gsub(/(_|-)/, ' ').titleize
+
+            # Some terms need to be capitalised all the time
+            uppercase_array = ['SMS', 'DTMF']
+            operation_id.split(' ').map do |c|
+              next c.upcase if uppercase_array.include?(c.upcase)
+              c
+            end.join(' ')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/helpers/url.rb

@@ -0,0 +1,17 @@
+module Nexmo
+  module OAS
+    module Renderer
+      module Helpers
+        module URL
+          def parameter_values(enum)
+            enum.map { |value| "<code>#{value}</code>" }.to_sentence(last_word_connector: ' or ', two_words_connector: ' or ')
+          end
+
+          def canonical_path
+            request.path.chomp("/#{params[:code_language]}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/lib/core_ext/string.rb

@@ -0,0 +1,14 @@
+class String
+  def render_markdown(options = {})
+    Nexmo::OAS::Renderer::MarkdownPipeline.new(options).call(self).html_safe
+  end
+
+  def unindent
+    indent = squeeze("\n").lines.map { |line| line.index(/[^\s]/) }.compact.min || 0
+    gsub(/^[[:blank:]]{#{indent}}/, '')
+  end
+
+  def unindent!
+    replace(unindent)
+  end
+end

data/lib/nexmo/oas/renderer/lib/redcarpet.rb

@@ -0,0 +1,14 @@
+require 'redcarpet'
+require 'rouge'
+require 'rouge/plugins/redcarpet'
+
+
+module Nexmo
+  module OAS
+    module Renderer
+      class HTML < Redcarpet::Render::HTML
+        include Rouge::Plugins::Redcarpet
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/models/code_snippet.rb

@@ -0,0 +1,75 @@
+module Nexmo
+  module OAS
+    module Renderer
+      module Models
+        class CodeSnippet
+          include ActiveModel::Model
+          attr_accessor :title, :product, :category, :navigation_weight, :document_path, :url
+
+          def self.by_product(product)
+            all.select do |block|
+              block.product == product
+            end
+          end
+
+          def self.all
+            blocks = files.map do |document_path|
+              document = File.read(document_path)
+              product = extract_product(document_path)
+
+              frontmatter = YAML.safe_load(document)
+
+              new({
+                title: frontmatter['title'],
+                navigation_weight: frontmatter['navigation_weight'] || 999,
+                product: product,
+                document_path: document_path,
+                category: extract_category(document_path),
+                url: generate_url(document_path),
+              })
+            end
+
+            blocks.sort_by(&:navigation_weight)
+          end
+
+          def self.generate_url(path)
+            '/' + path.gsub("#{origin}/", '').gsub('.md', '')
+          end
+
+          def self.extract_product(path)
+            # Remove the prefix
+            path = path.gsub!("#{origin}/", '')
+
+            # Each file is in the form code-snippets/<title>.md, so let's remove everything after code-snippets
+            path = path.gsub(%r{/code-snippets/.*}, '')
+
+            path
+          end
+
+          def self.extract_category(path)
+            # Remove the prefix
+            path = path.gsub("#{origin}/", '')
+
+            # Each file is in the form code-snippets/<title>.md, so let's capture everything after code-snippets
+            path = path.gsub(%r{.*/code-snippets/(.*)$}, '\1')
+
+            parts = path.split('/')
+            parts = parts[0...-1]
+
+            return nil if parts.empty?
+
+            parts.join('/').tr('-', ' ').humanize
+          end
+
+          def self.files
+            Dir.glob("#{origin}/**/code-snippets/**/*.md")
+          end
+
+          def self.origin
+            "_documentation"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/models/tutorial.rb

@@ -0,0 +1,83 @@
+module Nexmo
+  module OAS
+    module Renderer
+      module Models
+        class Tutorial
+
+          include ActiveModel::Model
+          attr_accessor :title, :description, :external_link, :products, :document_path, :languages
+
+          def body
+            File.read(document_path)
+          end
+
+          def path
+            return external_link if external_link
+            "/tutorials/#{document_path.relative_path_from(self.class.origin)}".gsub('.md', '')
+          end
+
+          def subtitle
+            normalized_products = products.map do |product|
+              normalise_product_title(product)
+            end
+
+            normalized_products.sort.to_sentence
+          end
+
+          def normalise_product_title(product)
+            return 'SMS' if product == 'messaging/sms'
+            return 'Voice' if product == 'voice/voice-api'
+            return 'Number Insight' if product == 'number-insight'
+            return 'Messages' if product == 'messages'
+            return 'Dispatch' if product == 'dispatch'
+            return 'Client SDK' if product == 'client-sdk'
+            product.camelcase
+          end
+
+          def self.by_product(product, tutorials = [])
+            tutorials = all if tutorials.empty?
+            tutorials.select do |tutorial|
+              tutorial.products.include? product
+            end
+          end
+
+          def self.by_language(language, tutorials = [])
+            language = language.downcase
+            tutorials = all if tutorials.empty?
+
+            tutorials.select do |tutorial|
+              tutorial.languages.map(&:downcase).include? language
+            end
+          end
+
+          def self.origin
+            Pathname.new("_tutorials")
+          end
+
+          def self.all
+            files.map do |document_path|
+              document_path = Pathname.new(document_path)
+              document = File.read(document_path)
+              frontmatter = YAML.safe_load(document)
+
+              new({
+                title: frontmatter['title'],
+                description: frontmatter['description'],
+                external_link: frontmatter['external_link'],
+                products: frontmatter['products'].split(',').map(&:strip),
+                languages: frontmatter['languages'] || [],
+                document_path: document_path,
+              })
+            end
+          end
+
+          private
+
+          private_class_method def self.files
+            Dir.glob("#{origin}/**/*.md")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/pipelines/markdown_pipeline.rb

@@ -0,0 +1,52 @@
+require 'banzai'
+
+Dir[File.join(__dir__, '../filters', '*.rb')].each { |f| require_relative f }
+
+module Nexmo
+  module OAS
+    module Renderer
+      class MarkdownPipeline < Banzai::Pipeline
+        def initialize(options = {})
+          super(
+            # As Markdown
+            Filters::Frontmatter,
+            Filters::PHPInliner,
+            Filters::InlineEscape,
+            Filters::BlockEscape,
+            Filters::Screenshot,
+            Filters::Anchor,
+            Filters::Audio,
+            Filters::DynamicContent,
+            Filters::Tooltip,
+            Filters::Collapsible,
+            Filters::Tab.new(options),
+            Filters::CodeSnippets.new(options),
+            Filters::CodeSnippet.new(options),
+            Filters::Code,
+            Filters::Indent,
+            Filters::Modal,
+            Filters::JsSequenceDiagram,
+            Filters::Partial.new(options),
+            Filters::Techio,
+            Filters::Tutorials,
+            Filters::CodeSnippetList,
+            Filters::ConceptList,
+            Filters::Language,
+            Filters::Columns,
+            Filters::Markdown.new(options),
+
+            # As HTML
+            Filters::UserPersonalization.new(options),
+            Filters::Heading,
+            Filters::Label.new(options),
+            Filters::Break,
+            Filters::Unfreeze,
+            Filters::Icon,
+            Filters::ExternalLink,
+            Filters::TutorialLink
+          )
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/presenters/api_specification.rb

@@ -0,0 +1,42 @@
+module Nexmo
+  module OAS
+    module Renderer
+      module Presenters
+        class ApiSpecification
+
+          def initialize(document_name:)
+            @document_name = document_name
+          end
+
+          def side_navigation
+            "api/#{@document_name}"
+          end
+
+          def document_path
+            "_api/#{@document_name}.md"
+          end
+
+          def document
+            @document ||= File.read(document_path)
+          end
+
+          def frontmatter
+            @frontmatter ||= YAML.safe_load(document)
+          end
+
+          def side_navigation_title
+            @side_navigation_title ||= frontmatter.fetch('api')
+          end
+
+          def document_title
+            @document_title ||= "#{side_navigation_title} > #{frontmatter.fetch('title')}"
+          end
+
+          def content
+            @content ||= MarkdownPipeline.new.call(document)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/presenters/groups.rb

@@ -0,0 +1,35 @@
+module Nexmo
+  module OAS
+    module Renderer
+      module Presenters
+        class Groups
+          def initialize(definition)
+            @definition = definition
+          end
+
+          def groups
+            tags = @definition.raw['tags']
+            # For now we only use the first tag in the list as an equivalent for the old x-group functionality
+            @groups = @definition.endpoints.group_by do |endpoint|
+              next nil unless tags
+              endpoint.raw['tags']&.first
+            end
+
+            # We want to use the order in which the tags are defined in the definition, so iterate over the tags
+            # and store the index against the tag name. We'll use this later for sorting
+            ordering = {}
+            tags&.each_with_index do |tag, index|
+              ordering[tag['name'].capitalize] = index
+            end
+
+            # Sort by the order in which they're defined in the definition
+            @groups = @groups.sort_by do |name, _|
+              next -1 if name.nil?
+              ordering[name.capitalize] || 999
+            end
+          end
+        end
+      end
+    end
+  end
+end