govuk_tech_docs 1.5.0 → 1.6.0

data/lib/assets/stylesheets/modules/_collapsible.scss

@@ -11,6 +11,10 @@
     display: block
   }
 }
+.collapsible__heading,
+.toc__list > ul > li > a:link.collapsible__heading {
+  margin-right: 30px;
+}
 .collapsible__toggle {
   position: absolute;
   top: 0;
@@ -34,12 +38,15 @@
   &::after {
     content: '';
     display: block;
-    background: no-repeat file-url('arrow-down.svg') center center;
-    background-size: 18px auto;
-    width: 20px;
-    height: 40px;
+    border: 2px solid $black;
+    border-width: 2px 2px 0 0;
+    transform: rotate(135deg);
+    width: 10px;
+    height: 10px;
+    margin-top: 10px;
   }
   .collapsible.is-open &::after {
-    background-image: file-url('arrow-up.svg');
+    transform: rotate(315deg);
+    margin-top: 18px;
   }
 }

data/lib/assets/stylesheets/modules/_technical-documentation.scss

@@ -3,11 +3,11 @@
 @mixin heading-offset($tabletTopMargin) {
   // Scale margins with font size on mobile (16/19ths)
   $mobileTopMargin: ceil($tabletTopMargin * (16 / 19));
-  
+
   // Offset headings down on mobile so that linking to anchors they appear after
   // the sticky 'table of contents' element
   $stickyTocOffset: 20px + $gutter-half + 10px + 1px;
-  
+
   // Pad the heading so that when linking to an anchor there is at most a
   // $gutter-half (mobile) or $gutter (tablet and above) sized gap between the
   // top of the viewport and the heading.
@@ -25,9 +25,9 @@
   display: block;
   margin: 0 $gutter-half 10px;
   max-width: 40em;
-  
+
   line-height: 1.4;
-  
+
   color: $text-colour;
 
   @include media(tablet) {
@@ -45,14 +45,14 @@
     @include bold-48;
     @include heading-offset($gutter * 2);
     border-top: 5px solid $text-colour;
-    
+
     &:first-of-type {
       @include heading-offset($gutter);
       border-top: none;
     }
   }
 
-  h2 {    
+  h2 {
     @include bold-36;
     @include heading-offset($gutter * 1.5);
   }
@@ -125,7 +125,7 @@
 
   ol + p, ul + p, .table-container + p {
     margin-top: ceil($gutter * (16 / 19));
-    
+
     @include media(tablet) {
       margin-top: $gutter;
     }
@@ -144,6 +144,11 @@
     overflow: auto;
     position: relative;
     border: 1px solid $code-02;
+    // Restrict the width of pre tags, as they have a tendency grow larger than
+    // the viewport when placed within table cells.
+    // @todo: Use table-layout: fixed, and remove the max-width definition from
+    // .technical-documentation so tables can fill the viewport.
+    max-width: 40em;
   }
 
   pre code {
@@ -156,11 +161,11 @@
     background: $code-01;
     padding: 3px 5px;
     border-radius: 1px;
-    
+
     font-family: monaco, Consolas, "Lucida Console", monospace;
     font-size: 15px;
     color: $code-0E;
-    
+
     @include media(tablet) {
       font-size: 16px;
     }
@@ -191,11 +196,11 @@
     display: block;
     max-width: 100%;
     overflow-x: auto;
-    
+
     margin-top: $gutter-half;
   }
 
-  table {    
+  table {
     width: 100%;
 
     border-collapse: collapse;

data/lib/assets/stylesheets/modules/_toc.scss

@@ -27,7 +27,7 @@
 
       a:link, a:visited {
         display: block;
-        padding: 8px 40px 8px $gutter-half;
+        padding: 8px $gutter 8px $gutter-half;
         margin: 0 $gutter-half * -1;
         border-left: 5px solid transparent;
 

data/lib/govuk_tech_docs.rb

@@ -20,6 +20,7 @@ require 'govuk_tech_docs/pages'
 require 'govuk_tech_docs/tech_docs_html_renderer'
 require 'govuk_tech_docs/unique_identifier_extension'
 require 'govuk_tech_docs/unique_identifier_generator'
+require 'govuk_tech_docs/api_reference/api_reference_extension'
 
 module GovukTechDocs
   # Configure the tech docs template
@@ -37,7 +38,9 @@ module GovukTechDocs
     context.set :markdown_engine, :redcarpet
     context.set :markdown,
         renderer: TechDocsHTMLRenderer.new(
-          with_toc_data: true
+          with_toc_data: true,
+          api: true,
+          context: context
         ),
         fenced_code_blocks: true,
         tables: true,
@@ -56,6 +59,8 @@ module GovukTechDocs
     context.config[:tech_docs] = YAML.load_file('config/tech-docs.yml').with_indifferent_access
     context.activate :unique_identifier
 
+    context.activate :api_reference
+
     context.helpers do
       include GovukTechDocs::TableOfContents::Helpers
       include GovukTechDocs::ContributionBanner
@@ -65,7 +70,7 @@ module GovukTechDocs
       end
 
       def current_page_review
-        @current_page_review ||= GovukTechDocs::PageReview.new(current_page)
+        @current_page_review ||= GovukTechDocs::PageReview.new(current_page, config)
       end
 
       def format_date(date)
@@ -102,6 +107,12 @@ module GovukTechDocs
           content: { boost: 50, store: true },
           url:     { index: false, store: true },
         }
+
+        search.pipeline_remove = [
+          'stopWordFilter'
+        ]
+
+        search.tokenizer_separator = '/[\s\-/]+/'
       end
     end
   end

data/lib/govuk_tech_docs/api_reference/api_reference_extension.rb

@@ -0,0 +1,100 @@
+require 'erb'
+require 'openapi3_parser'
+require 'uri'
+require 'pry'
+require 'govuk_tech_docs/api_reference/api_reference_renderer'
+
+module GovukTechDocs
+  module ApiReference
+    class Extension < Middleman::Extension
+      expose_to_application api: :api
+
+      def initialize(app, options_hash = {}, &block)
+        super
+
+        @app = app
+        @config = @app.config[:tech_docs]
+
+        # If no api path then just return.
+        if @config['api_path'].to_s.empty?
+          raise 'No api path defined in tech-docs.yml'
+        end
+
+        # Is the api_path a url or path?
+        if uri?(@config['api_path'])
+          @api_parser = true
+          @document = Openapi3Parser.load_url(@config['api_path'])
+        elsif File.exist?(@config['api_path'])
+          # Load api file and set existence flag.
+          @api_parser = true
+          @document = Openapi3Parser.load_file(@config['api_path'])
+        else
+          @api_parser = false
+          raise 'Unable to load api path from tech-docs.yml'
+        end
+        @render = Renderer.new(@app, @document)
+      end
+
+      def uri?(string)
+        uri = URI.parse(string)
+        %w(http https).include?(uri.scheme)
+      rescue URI::BadURIError
+        false
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def api(text)
+        if @api_parser == true
+
+          keywords = {
+            'api&gt;' => 'default',
+            'api_schema&gt;' => 'schema'
+          }
+
+          regexp = keywords.map { |k, _| Regexp.escape(k) }.join('|')
+
+          md = text.match(/^<p>(#{regexp})/)
+          if md
+            key = md.captures[0]
+            type = keywords[key]
+
+            text.gsub!(/#{ Regexp.escape(key) }\s+?/, '')
+
+            # Strip paragraph tags from text
+            text = text.gsub(/<\/?[^>]*>/, '')
+            text = text.strip
+
+            if text == 'api&gt;'
+              @render.api_full(api_info, api_server)
+            elsif type == 'default'
+              output = @render.path(text)
+              # Render any schemas referenced in the above path
+              output += @render.schemas_from_path(text)
+              output
+            else
+              @render.schema(text)
+            end
+
+          else
+            return text
+          end
+        else
+          text
+        end
+      end
+
+    private
+
+      def api_info
+        @document.info
+      end
+
+      def api_server
+        @document.servers[0]
+      end
+    end
+  end
+end
+
+::Middleman::Extensions.register(:api_reference, GovukTechDocs::ApiReference::Extension)

data/lib/govuk_tech_docs/api_reference/api_reference_renderer.rb

@@ -0,0 +1,279 @@
+require 'erb'
+require 'json'
+
+module GovukTechDocs
+  module ApiReference
+    class Renderer
+      def initialize(app, document)
+        @app = app
+        @document = document
+
+        # Load template files
+        @template_api_full = get_renderer('api_reference_full.html.erb')
+        @template_path = get_renderer('path.html.erb')
+        @template_schema = get_renderer('schema.html.erb')
+        @template_operation = get_renderer('operation.html.erb')
+        @template_parameters = get_renderer('parameters.html.erb')
+        @template_responses = get_renderer('responses.html.erb')
+      end
+
+      def api_full(info, server)
+        paths = ''
+        paths_data = @document.paths
+        paths_data.each do |path_data|
+          # For some reason paths.each returns an array of arrays [title, object]
+          # instead of an array of objects
+          text = path_data[0]
+          paths += path(text)
+        end
+        schemas = ''
+        schemas_data = @document.components.schemas
+        schemas_data.each do |schema_data|
+          text = schema_data[0]
+          schemas += schema(text)
+        end
+        @template_api_full.result(binding)
+      end
+
+      def path(text)
+        path = @document.paths[text]
+        id = text.parameterize
+        operations = operations(path, id)
+        @template_path.result(binding)
+      end
+
+      def schema(text)
+        schemas = ''
+        schemas_data = @document.components.schemas
+        schemas_data.each do |schema_data|
+          all_of = schema_data[1]["allOf"]
+          properties = []
+          if !all_of.blank?
+            all_of.each do |schema_nested|
+              schema_nested.properties.each do |property|
+                properties.push property
+              end
+            end
+          end
+
+          schema_data[1].properties.each do |property|
+            properties.push property
+          end
+
+          if schema_data[0] == text
+            title = schema_data[0]
+            schema = schema_data[1]
+            return @template_schema.result(binding)
+          end
+        end
+      end
+
+      def schemas_from_path(text)
+        path = @document.paths[text]
+        operations = get_operations(path)
+        # Get all referenced schemas
+        schemas = []
+        operations.compact.each_value do |operation|
+          responses = operation.responses
+          responses.each do |_rkey, response|
+            if response.content['application/json']
+              schema = response.content['application/json'].schema
+              schema_name = get_schema_name(schema.node_context.source_location.to_s)
+              if !schema_name.nil?
+                schemas.push schema_name
+              end
+              schemas.concat(schemas_from_schema(schema))
+            end
+          end
+        end
+        # Render all referenced schemas
+        output = ''
+        schemas.uniq.each do |schema_name|
+          output += schema(schema_name)
+        end
+        if !output.empty?
+          output.prepend('<h2 id="schemas">Schemas</h2>')
+        end
+        output
+      end
+
+      def schemas_from_schema(schema)
+        schemas = []
+        properties = []
+        schema.properties.each do |property|
+          properties.push property[1]
+        end
+        if schema.type == 'array'
+          properties.push schema.items
+        end
+        all_of = schema["allOf"]
+        if !all_of.blank?
+          all_of.each do |schema_nested|
+            schema_nested.properties.each do |property|
+              properties.push property[1]
+            end
+          end
+        end
+        properties.each do |property|
+          # Must be a schema be referenced by another schema
+          # And not a property of a schema
+          if property.node_context.referenced_by.to_s.include?('#/components/schemas') &&
+              !property.node_context.source_location.to_s.include?('/properties/')
+            schema_name = get_schema_name(property.node_context.source_location.to_s)
+          end
+          if !schema_name.nil?
+            schemas.push schema_name
+          end
+          # Check sub-properties for references
+          schemas.concat(schemas_from_schema(property))
+        end
+        schemas
+      end
+
+      def operations(path, path_id)
+        output = ''
+        operations = get_operations(path)
+        operations.compact.each do |key, operation|
+          id = "#{path_id}-#{key.parameterize}"
+          parameters = parameters(operation, id)
+          responses = responses(operation, id)
+          output += @template_operation.result(binding)
+        end
+        output
+      end
+
+      def parameters(operation, operation_id)
+        parameters = operation.parameters
+        id = "#{operation_id}-parameters"
+        output = @template_parameters.result(binding)
+        output
+      end
+
+      def responses(operation, operation_id)
+        responses = operation.responses
+        id = "#{operation_id}-responses"
+        output = @template_responses.result(binding)
+        output
+      end
+
+      def markdown(text)
+        if text
+          Tilt['markdown'].new(context: @app) { text }.render
+        end
+      end
+
+      def json_output(schema)
+        properties =  schema_properties(schema)
+        JSON.pretty_generate(properties)
+      end
+
+      def json_prettyprint(data)
+        JSON.pretty_generate(data)
+      end
+
+      def schema_properties(schema_data)
+        properties = Hash.new
+        if defined? schema_data.properties
+          schema_data.properties.each do |key, property|
+            properties[key] = property
+          end
+        end
+        properties.merge! get_all_of_hash(schema_data)
+        properties_hash = Hash.new
+        properties.each do |pkey, property|
+          if property.type == 'object'
+            properties_hash[pkey] = Hash.new
+            items = property.items
+            if !items.blank?
+              properties_hash[pkey] = schema_properties(items)
+            end
+            if !property.properties.blank?
+              properties_hash[pkey] = schema_properties(property)
+            end
+          elsif property.type == 'array'
+            properties_hash[pkey] = Array.new
+            items = property.items
+            if !items.blank?
+              properties_hash[pkey].push schema_properties(items)
+            end
+          else
+            properties_hash[pkey] = !property.example.nil? ? property.example : property.type
+          end
+        end
+
+        properties_hash
+      end
+
+    private
+
+      def get_all_of_array(schema)
+        properties = Array.new
+        if schema.is_a?(Array)
+          schema = schema[1]
+        end
+        if schema["allOf"]
+          all_of = schema["allOf"]
+        end
+        if !all_of.blank?
+          all_of.each do |schema_nested|
+            schema_nested.properties.each do |property|
+              if property.is_a?(Array)
+                property = property[1]
+              end
+              properties.push property
+            end
+          end
+        end
+        properties
+      end
+
+      def get_all_of_hash(schema)
+        properties = Hash.new
+        if schema["allOf"]
+          all_of = schema["allOf"]
+        end
+        if !all_of.blank?
+          all_of.each do |schema_nested|
+            schema_nested.properties.each do |key, property|
+              properties[key] = property
+            end
+          end
+        end
+        properties
+      end
+
+      def get_renderer(file)
+        template_path = File.join(File.dirname(__FILE__), 'templates/' + file)
+        template = File.open(template_path, 'r').read
+        ERB.new(template)
+      end
+
+      def get_operations(path)
+        operations = {}
+        operations['get'] = path.get if defined? path.get
+        operations['put'] = path.put if defined? path.put
+        operations['post'] = path.post if defined? path.post
+        operations['delete'] = path.delete if defined? path.delete
+        operations['patch'] = path.patch if defined? path.patch
+        operations
+      end
+
+      def get_schema_name(text)
+        unless text.is_a?(String)
+          return nil
+        end
+        # Schema dictates that it's always components['schemas']
+        text.gsub(/#\/components\/schemas\//, '')
+      end
+
+      def get_schema_link(schema)
+        schema_name = get_schema_name schema.node_context.source_location.to_s
+        if !schema_name.nil?
+          id = "schema-#{schema_name.parameterize}"
+          output = "<a href='\##{id}'>#{schema_name}</a>"
+          output
+        end
+      end
+    end
+  end
+end