dss_tech_docs 0.1.0

data/lib/govuk_tech_docs/api_reference/templates/api_reference_full.html.erb

@@ -0,0 +1,19 @@
+<h1 id="<%=  info.title.parameterize %>"><%= info.title %> v<%= info.version %></h1>
+<%= markdown(info.description) %>
+
+<% unless servers.empty? %>
+  <h2 id="servers">Servers</h2>
+  <div id="server-list">  
+    <% servers.each do |server| %>
+    <% if server.description %>
+    <p><strong><%= server.description %></strong></p>
+    <% end %>
+    <a href="<%= server.url %>"><%= server.url %></a>
+  <% end %>
+  </div>
+<% end %>
+
+<%= paths %>
+
+<h2 id="schemas">Schemas</h2>
+<%= schemas %>

data/lib/govuk_tech_docs/api_reference/templates/operation.html.erb

@@ -0,0 +1,11 @@
+<h3 id="<%= id %>"><%= key %></h3>
+<% if operation.summary %>
+  <p><em><%= operation.summary %></em></p>
+<% end %>
+<% if operation.description %>
+  <p><%= markdown(operation.description) %></p>
+<% end %>
+
+<%= parameters %>
+
+<%= responses %>

data/lib/govuk_tech_docs/api_reference/templates/parameters.html.erb

@@ -0,0 +1,28 @@
+<% if parameters.any? %>
+<h4 id="<%= id %>">Parameters</h4>
+<table>
+<thead>
+<tr><th>Parameter</th><th>In</th><th>Type</th><th>Required</th><th>Description</th></tr>
+</thead>
+<tbody>
+<% parameters.each do |parameter| %>
+<tr>
+<td><%= parameter.name %></td>
+<td><%= parameter.in %></td>
+<td><%= parameter.schema.type %></td>
+<td><%= parameter.required? %></td>
+<td><%= markdown(parameter.description) %>
+<% if parameter.schema.enum %>
+<p>Available items:</p>
+<ul>
+<% parameter.schema.enum.each do |item| %>
+<li><%= item %></li>
+<% end %>
+</ul>
+<% end %>
+</td>
+</tr>
+<% end %>
+</tbody>
+</table>
+<% end %>

data/lib/govuk_tech_docs/api_reference/templates/path.html.erb

@@ -0,0 +1,4 @@
+<% if text %>
+<h2 id="<%= id %>"><%= text %></h2>
+<% end %>
+<%= operations %>

data/lib/govuk_tech_docs/api_reference/templates/responses.html.erb

@@ -0,0 +1,33 @@
+<% if responses.any? %>
+<h4 id="<%= id %>">Responses</h4>
+<table>
+<thead>
+<tr><th>Status</th><th>Description</th><th>Schema</th></tr>
+</thead>
+<tbody>
+<% responses.each do |key,response| %>
+<tr>
+<td><%= key %></td>
+<td>
+<%= markdown(response.description) %>
+<% if response.content['application/json']
+if response.content['application/json']["example"]
+  request_body = json_prettyprint(response.content['application/json']["example"])
+else
+  request_body = json_output(response.content['application/json'].schema)
+end
+end %>
+<% if !request_body.blank? %>
+<pre><code><%= request_body %></code></pre>
+<% end %>
+</td>
+<td>
+<%= if response.content['application/json']
+  get_schema_link(response.content['application/json'].schema)
+end %>
+</td>
+</tr>
+<% end %>
+</tbody>
+</table>
+<% end %>

data/lib/govuk_tech_docs/api_reference/templates/schema.html.erb

@@ -0,0 +1,29 @@
+<h3 id="<%= id = 'schema-' + title; id.parameterize %>"><%= title %></h3>
+<%= markdown(schema.description) %>
+<% if properties.any? %>
+<table>
+<thead>
+<tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th><th>Schema</th></tr>
+</thead>
+<tbody>
+<% properties.each do |property| %>
+<tr>
+<td><%= property[0] %></td>
+<td><%= property[1].type %></td>
+<td><%= property[1].required.present? %></td>
+<td><%= markdown(property[1].description) %></td>
+<td>
+  <%=
+  schema = property[1]
+  # If property is an array, check the items property for a reference.
+  if property[1].type == 'array'
+    schema = property[1]['items']
+  end
+  # Only print a link if it's a referenced object.
+  get_schema_link(schema) if schema.node_context.referenced_by.to_s.include? '#/components/schemas' and !schema.node_context.source_location.to_s.include? '/properties/' %>
+</td>
+</tr>
+<% end %>
+</tbody>
+</table>
+<% end %>

data/lib/govuk_tech_docs/contribution_banner.rb

@@ -0,0 +1,62 @@
+module GovukTechDocs
+  # Helper included
+  module ContributionBanner
+    def source_urls
+      SourceUrls.new(current_page, config)
+    end
+  end
+
+  class SourceUrls
+    attr_reader :current_page, :config
+
+    def initialize(current_page, config)
+      @current_page = current_page
+      @config = config
+    end
+
+    def view_source_url
+      override_from_page || source_from_yaml_file || source_from_file
+    end
+
+    def report_issue_url
+      url = config[:source_urls]&.[](:report_issue_url)
+
+      if url.nil?
+        "#{repo_url}/issues/new?labels=bug&title=Re: '#{current_page.data.title}'&body=Problem with '#{current_page.data.title}' (#{config[:tech_docs][:host]}#{current_page.url})"
+      else
+        "#{url}?subject=Re: '#{current_page.data.title}'&body=Problem with '#{current_page.data.title}' (#{config[:tech_docs][:host]}#{current_page.url})"
+      end
+    end
+
+    def repo_url
+      "https://github.com/#{config[:tech_docs][:github_repo]}"
+    end
+
+    def repo_branch
+      config[:tech_docs][:github_branch] || 'master'
+    end
+
+  private
+
+    # If a `page` local exists, see if it has a `source_url`. This is used by the
+    # pages that are created by the proxy system because they can't use frontmatter
+    def override_from_page
+      locals.key?(:page) ? locals[:page].try(:source_url) : false
+    end
+
+    # In the frontmatter we can specify a `source_url`. Use this if the actual
+    # source of the page is in another GitHub repo.
+    def source_from_yaml_file
+      current_page.data.source_url
+    end
+
+    # As the last fallback link to the source file in this repository.
+    def source_from_file
+      "#{repo_url}/blob/#{repo_branch}/source/#{current_page.file_descriptor[:relative_path]}"
+    end
+
+    def locals
+      current_page.metadata[:locals]
+    end
+  end
+end

data/lib/govuk_tech_docs/meta_tags.rb

@@ -0,0 +1,67 @@
+module GovukTechDocs
+  class MetaTags
+    def initialize(config, current_page)
+      @config = config
+      @current_page = current_page
+    end
+
+    def tags
+      all_tags = {
+        'description' => page_description,
+        'og:description' => page_description,
+        'og:image' => page_image,
+        'og:site_name' => site_name,
+        'og:title' => page_title,
+        'og:type' => 'object',
+        'og:url' => canonical_url,
+        'twitter:card' => 'summary',
+        'twitter:domain' => URI.parse(host).host,
+        'twitter:image' => page_image,
+        'twitter:title' => browser_title,
+        'twitter:url' => canonical_url,
+      }
+
+      Hash[all_tags.select { |_k, v| v }]
+    end
+
+    def browser_title
+      [page_title, site_name].select(&:present?).uniq.join(' | ')
+    end
+
+    def canonical_url
+      "#{host}#{current_page.url}"
+    end
+
+  private
+
+    attr_reader :config, :current_page
+
+    def page_image
+      "#{host}/images/govuk-large.png"
+    end
+
+    def site_name
+      config[:tech_docs][:full_service_name] || config[:tech_docs][:service_name]
+    end
+
+    def page_description
+      locals[:description] || frontmatter.description
+    end
+
+    def page_title
+      locals[:title] || frontmatter.title
+    end
+
+    def host
+      config[:tech_docs][:host].to_s
+    end
+
+    def locals
+      current_page.metadata[:locals]
+    end
+
+    def frontmatter
+      current_page.data
+    end
+  end
+end

data/lib/govuk_tech_docs/page_review.rb

@@ -0,0 +1,52 @@
+module GovukTechDocs
+  class PageReview
+    attr_reader :page
+
+    def initialize(page, config = {})
+      @page = page
+      @config = config
+    end
+
+    def review_by
+      return unless last_reviewed_on
+
+      @review_by ||= Chronic.parse(
+        "in #{page.data.review_in}",
+        now: last_reviewed_on.to_time
+      ).to_date
+    end
+
+    def under_review?
+      page.data.review_in.present?
+    end
+
+    def last_reviewed_on
+      page.data.last_reviewed_on
+    end
+
+    def owner_slack
+      page.data.owner_slack || default_owner_slack
+    end
+
+    def owner_slack_url
+      return "" unless owner_slack_workspace
+      # Slack URLs don't have the # (channels) or @ (usernames)
+      slack_identifier = owner_slack.to_s.delete('#').delete('@')
+      "https://#{owner_slack_workspace}.slack.com/messages/#{slack_identifier}"
+    end
+
+    def show_expiry?
+      @config[:tech_docs].fetch(:show_expiry, true)
+    end
+
+  private
+
+    def default_owner_slack
+      @config[:tech_docs][:default_owner_slack]
+    end
+
+    def owner_slack_workspace
+      @config[:tech_docs][:owner_slack_workspace]
+    end
+  end
+end

data/lib/govuk_tech_docs/pages.rb

@@ -0,0 +1,32 @@
+module GovukTechDocs
+  class Pages
+    attr_reader :sitemap
+
+    def initialize(sitemap, config)
+      @sitemap = sitemap
+      @config = config
+    end
+
+    def to_json
+      as_json.to_json
+    end
+
+  private
+
+    def as_json
+      pages.map do |page|
+        review = PageReview.new(page, @config)
+        {
+          title: page.data.title,
+          url: "#{@config[:tech_docs][:host]}#{page.url}",
+          review_by: review.review_by,
+          owner_slack: review.owner_slack,
+        }
+      end
+    end
+
+    def pages
+      sitemap.resources.select { |page| page.data.title }
+    end
+  end
+end

data/lib/govuk_tech_docs/redirects.rb

@@ -0,0 +1,39 @@
+module GovukTechDocs
+  class Redirects
+    LEADING_SLASH = %r[\A\/]
+
+    def initialize(context)
+      @context = context
+    end
+
+    def redirects
+      all_redirects = redirects_from_config + redirects_from_frontmatter
+
+      all_redirects.map do |from, to|
+        # Middleman needs paths without leading slashes
+        [from.sub(LEADING_SLASH, ''), to: to.sub(LEADING_SLASH, '')]
+      end
+    end
+
+  private
+
+    attr_reader :context
+
+    def redirects_from_config
+      context.config[:tech_docs][:redirects].to_a
+    end
+
+    def redirects_from_frontmatter
+      reds = []
+      context.sitemap.resources.each do |page|
+        next unless page.data.old_paths
+
+        page.data.old_paths.each do |old_path|
+          reds << [old_path, page.path]
+        end
+      end
+
+      reds
+    end
+  end
+end

data/lib/govuk_tech_docs/table_of_contents/heading.rb

@@ -0,0 +1,30 @@
+module GovukTechDocs
+  module TableOfContents
+    class Heading
+      def initialize(element_name:, text:, attributes:, page_url: '')
+        @element_name = element_name
+        @text = text
+        @attributes = attributes
+        @page_url = page_url
+      end
+
+      def size
+        @element_name.scan(/h(\d)/) && $1 && Integer($1)
+      end
+
+      def href
+        @page_url + '#' + @attributes['id']
+      end
+
+      def title
+        @text
+      end
+
+      def ==(other)
+        @element_name == other.instance_variable_get("@element_name") &&
+          @text == other.instance_variable_get("@text") &&
+          @attributes == other.instance_variable_get("@attributes")
+      end
+    end
+  end
+end

data/lib/govuk_tech_docs/table_of_contents/heading_tree.rb

@@ -0,0 +1,27 @@
+module GovukTechDocs
+  module TableOfContents
+    class HeadingTree
+      attr_accessor :parent, :heading, :children
+
+      def initialize(parent: nil, heading: nil, children: [])
+        @parent = parent
+        @heading = heading
+        @children = children
+      end
+
+      def depth
+        if parent
+          parent.depth + 1
+        else
+          1
+        end
+      end
+
+      def ==(other)
+        heading == other.heading &&
+          children.length == other.children.length &&
+          children.map.with_index { |child, index| child == other.children[index] }.all?
+      end
+    end
+  end
+end