govuk_tech_docs 6.2.4 → 6.3.0

data/documentation/source/support/index.html.md.erb

@@ -0,0 +1,46 @@
+---
+title: Support
+weight: 80
+last_reviewed_on: 2020-07-01
+review_in: 1 year
+---
+
+# Support
+
+## Report issues
+
+Report any problems or issues by:
+
+- contacting the Government Digital Service (GDS) technical writing community on [email][contact-email] or [Slack][slack-ask-tw]
+- posting in the [tech docs format][slack-tech-docs-format] Slack channel
+- opening an issue on the [tech-docs-template repo][template-issues]
+
+## Contribute
+
+We welcome contributions to the Technical Documentation Template.
+
+You can create an issue or pull request in the following GitHub repos:
+
+- [alphagov/tech-docs-gem][tech-docs-gem] - for technical and documentation issues
+- [alphagov/tech-docs-template][tech-docs-template]
+
+You should check and document your pull request before you submit it.
+
+1. Check the repo to see if someone has already raised a similar pull request or issue.
+2. Test your contribution using [unit tests](https://github.com/alphagov/tech-docs-gem/tree/main/spec/govuk_tech_docs), [JavaScript tests](https://github.com/alphagov/tech-docs-gem/tree/main/spec/javascripts) and [integration tests](https://github.com/alphagov/tech-docs-gem/tree/main/spec/features).
+3. Document the change in this documentation.
+4. Add a description of the change to the repo changelog if your pull request changes how the Technical Documentation Template behaves.
+
+The Tech Docs Template working group will review your proposal at their next fortnightly triage session.
+
+The team will then do one of the following:
+
+- accept your proposal but ask for changes before it's prioritised for publication
+- accept your proposal and find someone to work with you to publish the changes
+- not accept your proposal and explain why
+
+## Projects that use the template
+
+You can see [which repos currently use the Tech Docs Template](https://github.com/alphagov/tech-docs-gem/network/dependents) in the Tech Docs Template Ruby gem GitHub repo.
+
+<%= partial "partials/links" %>

data/documentation/source/write_docs/add_openapi_spec/index.html.md.erb

@@ -0,0 +1,48 @@
+---
+title: Convert an OpenAPI specification into documentation
+weight: 42
+last_reviewed_on: 2021-07-06
+review_in: 1 year
+---
+
+# Convert an OpenAPI specification into documentation
+
+OpenAPI is an API description format for REST APIs. The government's Open Standards Board [recommends using OpenAPI][use-openapi].
+
+You can convert an OpenAPI file into an API reference page in your documentation.
+
+Your OpenAPI file must be both:
+
+- [version 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md)
+- in YAML format
+
+1. Add the following to your `config/tech-docs.yml` file:
+
+    ```yaml
+    api_path: <OPENAPI_FILE>
+    ```
+
+    where `<OPENAPI_FILE>` is your OpenAPI file, for example `/openapi/openapi.yaml`.
+
+2. Add the following in your documentation to convert the OpenAPI file into an API reference:
+
+    ```markdown
+    api>
+    ```
+
+For `api_path` you can also use:
+
+- a relative path, for example `./openapi/openapi.yaml`
+- an external file, for example `https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml`
+
+## Convert a specific endpoint
+
+You can convert a specific endpoint using the following in your documentation: 
+
+```markdown
+api> <ENDPOINT>
+```
+
+where `<ENDPOINT>` is your endpoint, for example `/pets`.
+
+<%= partial "partials/links" %>

data/documentation/source/write_docs/content/index.html.md.erb

@@ -0,0 +1,128 @@
+---
+title: Write your content
+weight: 41
+last_reviewed_on: 2020-07-01
+review_in: 1 year
+---
+# Write your content
+
+You can write your content in Markdown or HTML when using the Tech Doc Template.
+
+## Insert a table
+
+You can insert a table using either Markdown or HTML.
+
+Use Markdown when there are no specific formatting requirements.
+
+Use HTML when there are specific formatting requirements, for example to ensure that text in cells does not wrap.
+
+### Create table using Markdown
+
+Use Markdown when there are no specific formatting requirements.
+
+This example is a left-aligned table.
+
+```bash
+| Column header | Column header |
+|---------------|---------------|
+| content       | content       |
+| content       | content       |
+```
+
+Add more columns and rows as needed.
+
+You can change the alignment of the text in each column:
+
+- Centre: `|:---:|`
+- Right: `|---:|`
+
+If a table has 3 or more columns, you might need to set row headers as well as column headers to improve accessibility. Using row headers reduces the amount of information screen reader users need to remember whilst using the table.
+
+The following example has the first cell in each row marked up as the row header using the `#` character:
+
+```bash
+| City name         | Population | Average age |
+|-------------------|------------|-------------|
+| # Some city       | 38000      | 48          |
+| # Some other city | 41000      | 37          |
+```
+
+See the [Web Accessibility Initiative tutoral on table concepts](https://www.w3.org/WAI/tutorials/tables/) for more information.
+
+### Create table using HTML
+
+You should create tables using HTML when there are specific formatting requirements.
+
+The following code is an example of a 2 column 2 row table with no text wrapping.
+
+```bash
+<div style = "overflow-x:auto;">
+<table style="width:100%">
+<tr>
+<th nowrap>Header 1</th>
+<th>Header 2</th>
+</tr>
+<tr>
+<td nowrap><code>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et enim quis arcu pharetra aliquet. Maecenas posuere tellus arcu, a suscipit dui posuere eu. Nunc vestibulum ligula sit amet eros euismod accumsan. </code></td>
+<td nowrap>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et enim quis arcu pharetra aliquet. Maecenas posuere tellus arcu, a suscipit dui posuere eu. Nunc vestibulum ligula sit amet eros euismod accumsan. </td>
+</tr>
+</table>
+</div>
+```
+
+## Create a link
+
+You can create links using either Markdown or HTML.
+
+To create a link in Markdown, use the following:
+
+```yaml
+[link text](link address)
+```
+
+For example:
+
+```yaml
+[The Google home page](http://www.google.co.uk)
+```
+
+To create a link in HTML, use the following:
+
+```bash
+<a href="link address">link text</a>
+```
+
+You can write the link in HTML with a `target="blank"` element to make the link open in a new internet browser tab by default:
+
+```bash
+<a href="link address" target="blank">link text</a>
+```
+
+## Insert an image
+
+To insert an image into your content, use the following:
+
+```bash
+<%= image_tag "image file", { :alt => 'image alt text' } %>
+```
+
+You must include alt text for an image if the image has not been explained in surrounding content, due to accessibility requirements.
+
+## Insert a warning
+
+Use the warning text component when you need to warn users about something important, such as legal consequences of an action, or lack of action, that they might take.
+
+This warning text format is consistent with the [GOV.UK Design System warning text][design-system].
+
+To insert a warning, use the following:
+
+```ruby
+<%%= warning_text('insert warning text here') %>
+```
+
+## Use the GOV.UK Design System
+
+Use [GOV.UK Design System](https://design-system.service.gov.uk/) elements in your documentation to ensure your content complies with accessibility regulations.
+
+
+<%= partial "partials/links" %>

data/documentation/source/write_docs/index.html.md.erb

@@ -0,0 +1,15 @@
+---
+title: Write your documentation
+weight: 40
+last_reviewed_on: 2020-07-01
+review_in: 1 year
+---
+
+# Write your documentation
+
+When you write your documentation, you can:
+
+- [write your content][write-content] in Markdown and / or HTML
+- add an [OpenAPI3 specification][openapi3] to your documentation site
+
+<%= partial "partials/links" %>

data/exe/tech_docs_jobs

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+require "rake"
+
+Rake.application.init
+
+Dir.glob(File.join(__dir__, "../lib/tasks/*.rake")).each { |r| load r }
+
+Rake.application.top_level

data/lib/govuk_tech_docs/version.rb

@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "6.2.4".freeze
+  VERSION = "6.3.0".freeze
 end

data/lib/govuk_tech_docs/warning_text_extension.rb

@@ -5,6 +5,7 @@ module GovukTechDocs
     end
 
     helpers do
+      warn("This functionality is deprecated and will be removed in a future release. \n You should use the GOV.UK warning text component instead.")
       def warning_text(text)
         <<~EOS
         <div class="govuk-warning-text">

data/lib/source/layouts/_footer.erb

@@ -1,4 +1,4 @@
-<footer class="govuk-footer app-footer" role="contentinfo">
+<div class="govuk-footer app-footer" role="contentinfo">
   <% if config[:tech_docs][:show_govuk_logo] %>
   <svg focusable="false" role="presentation" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 60" height="30" width="32" fill="currentcolor" class="govuk-footer__crown">
     <g>
@@ -57,4 +57,4 @@
       >© Crown copyright</a>
     </div>
   </div>
-</footer>
+</div>

data/lib/source/layouts/_header.erb

@@ -1,4 +1,4 @@
-<header class="govuk-header app-header" role="banner" data-module="govuk-header">
+<div class="govuk-header app-header" role="banner" data-module="govuk-header">
   <div class="govuk-header__container govuk-header__container--full-width">
     <div class="govuk-header__logo">
       <% if config[:tech_docs][:service_link] %>
@@ -46,4 +46,4 @@
       <% end %>
     </div>
   </div>
-</header>
+</div>

data/lib/source/layouts/_service_navigation.erb

@@ -1,7 +1,4 @@
-<% if config[:tech_docs][:header_links] %>
-<div class="govuk-service-navigation app-pane__navigation"
-  data-module="govuk-service-navigation">
-  <div class="govuk-width-container">
+ <div class="govuk-width-container">
     <div class="govuk-service-navigation__container">
       <nav aria-label="Menu" class="govuk-service-navigation__wrapper">
         <button type="button" class="govuk-service-navigation__toggle govuk-js-service-navigation-toggle" aria-controls="navigation" hidden aria-hidden="true">
@@ -23,5 +20,3 @@
       </nav>
     </div>
   </div>
-</div>
-<% end %>

data/lib/source/layouts/core.erb

@@ -50,13 +50,19 @@
 
   <body class="govuk-template__body">
     <script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');</script>
+    <header class="govuk-template__header app-header" role="banner" data-module="govuk-header">
+      <%= partial 'layouts/header' %>
+    </header>
+    <% if config[:tech_docs][:header_links] %>
+      <div class="govuk-service-navigation app-pane__navigation" data-module="govuk-service-navigation">
+        <%= partial 'layouts/service_navigation' %>
+      </div>
+    <% end %>
+
 
-    <div class="app-pane">
       <%= partial 'layouts/cookie_banner' %>
       <div class="app-pane__header toc-open-disabled">
         <a href="#content" class="govuk-skip-link" data-module="govuk-skip-link">Skip to main content</a>
-        <%= partial 'layouts/header' %>
-        <%= partial 'layouts/service_navigation' %>
       </div>
 
       <% if content_for? :sidebar %>
@@ -81,7 +87,7 @@
         <% end %>
 
         <div class="app-pane__content toc-open-disabled" aria-label="Content">
-          <main id="content" class="technical-documentation"<% if config[:tech_docs][:enable_anchored_headings] != false %> data-module="anchored-headings"<% end %>>
+          <main id="content" class="govuk-main-wrapper technical-documentation"<% if config[:tech_docs][:enable_anchored_headings] != false %> data-module="anchored-headings"<% end %>>
             <%= yield %>
             <%= partial "layouts/page_review" %>
           </main>
@@ -95,11 +101,13 @@
               </ul>
             <% end %>
           </aside>
-
-          <%= partial "layouts/footer" %>
         </div>
       </div>
-    </div>
+
+
+    <footer class="govuk-template__footer">
+      <%= partial "layouts/footer" %>
+    </footer>
 
     <%= partial 'layouts/analytics' %>
     <%= javascript_include_tag :govuk_frontend, :type => "module" %>

data/lib/tasks/helpers/linter_report.rb

@@ -0,0 +1,49 @@
+class LinterReport
+  attr_accessor :linter_raw_output, :linter_summary_report, :linter_full_report
+
+  def initialize(raw_output)
+    puts "#{self.class} initialized."
+    @linter_raw_output = raw_output
+  end
+
+  def format_linter_output
+    raise NotImplementedError, "Subclass must implement #format_linter_output"
+  end
+
+  def get_raw_output
+    raise "No raw output available.  Check you have run the linter task correctly" unless @linter_raw_output
+
+    @linter_raw_output
+  end
+
+  def set_linter_summary_report
+    raise "Subclass must implement #set_linter_summary_report"
+  end
+
+  def get_linter_summary_report
+    raise "No output summary available.  Check you have called set_linter_summary_report" unless @linter_summary_report
+
+    @linter_summary_report
+  end
+
+  def set_linter_full_report
+    raise "Subclass must implement #set_linter_full_report"
+  end
+
+  def get_linter_full_report
+    raise "No output detail available.  Check you have called set_linter_full_report" unless @linter_full_report
+
+    @linter_full_report
+  end
+
+protected
+
+  def set_output_text_color(text, severity)
+    case severity.downcase
+    when "error" then "\e[31m#{text}\e[0m" # Red
+    when "warning" then "\e[33m#{text}\e[0m" # Yellow
+    when "suggestion" then "\e[34m#{text}\e[0m" # Blue
+    else "\e[36m#{text}\e[0m" # Cyan
+    end
+  end
+end

data/lib/tasks/helpers/rake_utils.rb

@@ -0,0 +1,7 @@
+def get_gem_root
+  Gem::Specification.find_by_name("govuk_tech_docs").gem_dir
+end
+
+def vale_config_path
+  File.join(get_gem_root, ".vale.ini")
+end

data/lib/tasks/helpers/vale_report.rb

@@ -0,0 +1,156 @@
+require_relative "./linter_report"
+require "json"
+
+class ValeLinterReport < LinterReport
+  attr_accessor :table_rows, :linter_severity_totals, :table_column_widths, :formatter, :linter_summary_report_json, :linter_full_report_json
+
+  def format_linter_output
+    if @linter_raw_output.strip.empty?
+      @table_rows = []
+      @linter_severity_totals = { "error" => 0, "warning" => 0, "suggestion" => 0 }
+    else
+      set_table_rows
+      set_linter_severity_totals_from_rows
+    end
+
+    set_linter_full_report
+    set_linter_summary_report
+    set_linter_summary_report_json
+  end
+
+  def set_linter_full_report
+    add_formatted_rows_to_detail_output
+  end
+
+  def set_linter_summary_report
+    if @linter_severity_totals.nil?
+      set_linter_severity_totals_from_rows
+    end
+
+    error = @linter_severity_totals["error"]
+    warning = @linter_severity_totals["warning"]
+    suggestion = @linter_severity_totals["suggestion"]
+
+    @linter_summary_report = []
+
+    @linter_summary_report << "\n#{'=' * [0, 40].max}"
+    @linter_summary_report << "\e[1m Vale summary\e[0m"
+    @linter_summary_report << "-" * [0, 40].max
+    @linter_summary_report << "  Errors:      #{error.positive? ? set_output_text_color(error, 'error') : error}"
+    @linter_summary_report << "  Warnings:    #{warning.positive? ? set_output_text_color(warning, 'warning') : warning}"
+    @linter_summary_report << "  Suggestions: #{suggestion.positive? ? set_output_text_color(suggestion, 'suggestion') : suggestion}"
+    @linter_summary_report << "-" * [0, 40].max
+    @linter_summary_report.join("\n")
+  end
+
+  def set_linter_summary_report_json
+    if @linter_severity_totals.nil?
+      set_linter_severity_totals_from_rows
+    end
+    @linter_summary_report_json = JSON.generate(@linter_severity_totals)
+  end
+
+private
+
+  def set_table_column_widths
+    if @table_rows.nil?
+      set_table_rows
+    end
+
+    @table_column_widths = %i[file line severity message rule].each_with_object({}) do |col, acc|
+      all_values = @table_rows.map { |row| row[col].to_s }
+      acc[col] = [col.to_s.length, *all_values.map(&:length)].max
+    end
+  end
+
+  def set_table_formatter
+    if @table_column_widths.nil?
+      set_table_column_widths
+    end
+    @formatter = "%-#{@table_column_widths[:file]}s | %-#{@table_column_widths[:line]}s | %-#{@table_column_widths[:severity]}s | %-#{@table_column_widths[:message]}s | %-#{@table_column_widths[:rule]}s"
+  end
+
+  def add_formatted_header_to_detail_output
+    if @linter_full_report.nil?
+      @linter_full_report = []
+    end
+
+    header = sprintf(@formatter, "File", "Line", "Severity", "Message", "Rule")
+    @linter_full_report << "\e[1m🔍 Vale Style Linting Report\e[0m\n\n"
+    @linter_full_report << "\e[1m#{header}\e[0m"
+    @linter_full_report << "-" * header.gsub(/\e\[[0-9;]*m/, "").length
+  end
+
+  def add_formatted_rows_to_detail_output
+    set_table_column_widths
+    set_table_formatter
+    add_formatted_header_to_detail_output
+
+    @table_rows.each do |row|
+      @linter_full_report << format_row(row)
+    end
+    @linter_full_report.join("\n")
+  end
+
+  def set_linter_severity_totals_from_rows
+    if @table_rows.nil?
+      set_table_rows
+    end
+
+    default_totals = { "error" => 0, "warning" => 0, "suggestion" => 0 }
+
+    @linter_severity_totals = default_totals.merge(
+      @table_rows
+        .map { |r| r[:severity] }
+        .compact # drops any actual nils
+        .tally,
+    )
+  end
+
+  def format_row(row)
+    colored_severity = set_output_text_color(row[:severity].upcase, row[:severity])
+    severity_padding = " " * (@table_column_widths[:severity] - row[:severity].length)
+    padded_severity = "#{colored_severity}#{severity_padding}"
+
+    sprintf(
+      @formatter,
+      row[:file], row[:line], padded_severity, row[:message], row[:rule]
+    )
+  end
+
+  def set_table_rows
+    begin
+      rows_json = JSON.parse(@linter_raw_output)
+    rescue JSON::ParserError
+      puts "\e[Error parsing Vale payload:\e[0m\n#{@linter_raw_output}"
+      exit 1
+    end
+
+    unique_rows = []
+
+    rows_json.each do |file_path, alerts|
+      next if alerts.empty?
+
+      seen_messages = Set.new
+
+      alerts.each do |alert|
+        msg = alert["Message"]
+        # Vale will hilghlight every instance of an infraction, sometimes this is unhelpful.  For example the acronyms rule needs to highlight an acronym is not defined in the first use
+        # it does not need to then point out every single time it is referenced in the document, so we check for itentical messages for specific rules
+        if seen_messages.include?(msg) && alert["Check"].downcase == "tech-writing-style-guide.acronyms"
+          next
+        end
+
+        seen_messages.add(msg)
+        unique_rows << {
+          file: file_path,
+          line: alert["Line"].to_s,
+          severity: alert["Severity"],
+          message: msg,
+          rule: alert["Check"],
+        }
+      end
+    end
+    @table_rows = unique_rows
+  end
+end

data/lib/tasks/lint.rake

@@ -0,0 +1,33 @@
+# Rakefile
+require "json"
+require "open3"
+require_relative "./helpers/rake_utils"
+require_relative "./helpers/vale_report"
+
+namespace :lint do
+  # task vale_sync:
+  desc "Run tech-docs-linter to check content against GOV.UK style guide."
+  task :vale, [:target, :clean_build, :full_output] do |_t, args|
+    args.with_defaults(target: "./build", clean_build: "true", full_output: "true")
+
+    sh "bundle exec vale sync --config='#{vale_config_path}'"
+
+    if args.clean_build == "true"
+      Rake::Task["middleman:build"].invoke
+    end
+
+    stdout, = Open3.capture3("vale --config='#{vale_config_path}' --output=JSON #{args.target}")
+
+    linter_report = ValeLinterReport.new(stdout)
+    linter_report.format_linter_output
+    if args.full_output == "true"
+      puts linter_report.get_linter_full_report
+    end
+    puts linter_report.get_linter_summary_report
+
+    # finish with a Ci friendly json string
+    linter_report.linter_summary_report_json
+    # Always exit 0 so individual project pipelines can evaluate the data themselves
+    exit 0
+  end
+end

data/lib/tasks/middleman.rake

@@ -0,0 +1,10 @@
+namespace :middleman do
+  desc "Delete build directory and run bundle exec middleman build"
+  task :build do
+    if Dir.exist?("./build")
+      puts "Target directory found at ./build.  Removing old build."
+      FileUtils.rm_rf("./build")
+    end
+    sh "bundle exec middleman build"
+  end
+end

data/node_modules/govuk-frontend/dist/govuk/_base.import.scss

@@ -0,0 +1,6 @@
+@import "settings";
+@import "tools";
+@import "helpers";
+@import "custom-properties";
+@import "components/button/settings";
+

data/node_modules/govuk-frontend/dist/govuk/_base.scss

@@ -1,6 +1,5 @@
-@import "settings/index";
-@import "tools/index";
-@import "helpers/index";
-@import "custom-properties/index";
+@forward "settings";
+@forward "tools";
+@forward "helpers";
+@forward "components/button/settings";
 
-/*# sourceMappingURL=_base.scss.map */