govuk_tech_docs 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a0b627893fa39ba6cc6484a977b7b9c00639ad28
-  data.tar.gz: a45ebcff76937b949bb5c7388359bbd26cbe1d53
+  metadata.gz: 7e106d8464ee73119270e939801832a1e49118a7
+  data.tar.gz: 334c5c672945bd52df62772578ccb862356cafd1
 SHA512:
-  metadata.gz: fe4b821226d40bff2fd3d2eff34887862e74eda39c00ef058f512b448f995d1d0181aff90e3448c5493108dbae2eb76d5ee34746a5c7077adb4fede3107c3553
-  data.tar.gz: b9e34c88cfc72c46f4cab5e73bd3946e4475e6a1a3a42f2140ef8fb024f48f57ef6f8e57a8f1dc5b47aef41a9ccf7f07bb7ce080d6cb7f81a806da52d5ee8881
+  metadata.gz: b507269b3da54e98e28db73fb89a0d4f2f2e1032f0829f2c3a7acc2401eb4f24b37e6776c16b6fdd0bfe49693a3df270ca8a68fcc162a78bbc380f5ec68d68f1
+  data.tar.gz: d825189334f2ea5612ca72836d2259a7d983c0b20ea5a559f7c1c9e61d47647700964ab20dca97d2f66bd3e2cf187681725becab2cb089e2343a7dfa49b89cf0

data/.rubocop.yml

@@ -6,3 +6,6 @@ Naming/HeredocDelimiterNaming:
 
 Lint/NestedMethodDefinition:
   Enabled: false
+
+Performance/HashEachMethods:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## Unreleased
+
+## 1.6.0
+
+Version 1.6.0 adds API reference generation, and improves the search function.
+
+### New feature: API reference
+
+Specify an OpenAPI spec file using `api_path`, for example: `api_path: source/pets.yml`.
+
+To output the generated content in the page of your choice, write `api>` in any markdown parsed file (.md, .html.md, .html.md.erb). You can also specify to just print a specific path: `api> /pets`
+
+This generates request and response schemas and examples for each API operation.
+
+More info:
+
+- https://github.com/alphagov/tech-docs-gem/pull/40
+- https://github.com/alphagov/tech-docs-gem/pull/48
+
+### Search result improvements
+
+The search indexing pipeline has been tweaked to provide expected results. The display of the search results has also been
+
+If you're using search then you'll need to add this line to your project `Gemfile`:
+
+```
+gem 'middleman-search', git: 'git://github.com/alphagov/middleman-search.git'
+```
+
+More info:
+- https://github.com/alphagov/tech-docs-gem/pull/37
+- https://github.com/alphagov/tech-docs-gem/pull/38
+- https://github.com/alphagov/tech-docs-gem/pull/41
+- https://github.com/alphagov/tech-docs-gem/pull/42
+- https://github.com/alphagov/tech-docs-gem/pull/43
+
+### Correct fork of middleman in example project
+
+The example gem project now uses alphagov/middleman-search. This prevents `bundle exec middleman serve` from crashing.
+
+More info:
+- https://github.com/alphagov/tech-docs-gem/pull/35
+
+### Accessibility improvements
+
+Accessibility improvements to search, collapsible navigation, and the logo.
+
+More info:
+- https://github.com/alphagov/tech-docs-gem/pull/36
+- https://github.com/alphagov/tech-docs-gem/pull/33
+
+### Additional configuration options for review system
+
+`default_owner_slack` and `owner_slack_workspace` are now configurable for use within the review system.
+
+More info:
+- https://github.com/alphagov/tech-docs-gem/pull/47
+
+### Correct fork of middleman in example project
+
+The example gem project now uses alphagov/middleman-search. This prevents `bundle exec middleman serve` from crashing.
+
+More info:
+- https://github.com/alphagov/tech-docs-gem/pull/35
+
+### Accessibility improvements
+
+Accessibility improvements to search, collapsible navigation, and the logo.
+
+More info:
+- https://github.com/alphagov/tech-docs-gem/pull/36
+- https://github.com/alphagov/tech-docs-gem/pull/33
+
+### Search result improvements
+
+The search indexing pipeline has been tweaked to provide expected results. The display of the search results has also been improved.
+
+If you're using search then you'll need to add this line to your project `Gemfile`:
+
+```
+gem 'middleman-search', git: 'git://github.com/alphagov/middleman-search.git'
+```
+
+More info:
+- https://github.com/alphagov/tech-docs-gem/pull/37
+- https://github.com/alphagov/tech-docs-gem/pull/38
+- https://github.com/alphagov/tech-docs-gem/pull/41
+- https://github.com/alphagov/tech-docs-gem/pull/42
+- https://github.com/alphagov/tech-docs-gem/pull/43
+
 ## 1.5.0
 
 ### New feature: Search

data/docs/configuration.md

@@ -148,3 +148,18 @@ default: `true`
 ```yaml
 show_govuk_logo: true
 ```
+
+## `api_path`
+
+Define a path to an Open API V3 spec file. This can be a relative file path or a URI to a raw file.
+
+```yaml
+api_path: ./source/pets.yml
+```
+
+## `owner_slack_workspace` and `default_owner_slack`
+
+These attributes are used to specify the owner of a page.  See the separate
+[documentation for page expiry][expiry] for more details.
+
+[expiry]: https://alphagov.github.io/tech-docs-manual/#page-expiry-and-review-notices

data/docs/frontmatter.md

@@ -5,24 +5,12 @@
 ## `last_reviewed_on` and `review_in`
 
 These attributes determine the date when the page needs to be reviewed next.
+See the separate [documentation for page expiry][expiry] for more details.
 
-If the page doesn't need to be reviewed, we show a blue box with the last-reviewed date, when it needs review again, and the owner.
-
-![](not-expired-page.png)
-
-If the page needs to be reviewed, we show a red box saying the page might not be accurate.
-
-![](expired-page.png)
+[expiry]: https://alphagov.github.io/tech-docs-manual/#page-expiry-and-review-notices
 
 Example:
 
-```yaml
----
-last_reviewed_on: 2018-01-18
-review_in: 6 weeks
----
-```
-
 You can use this in combination with [owner_slack](#owner-slack) to set an owner for the page.
 
 ## `layout`

data/docs/page-expiry.md

@@ -0,0 +1,69 @@
+# Page Expiry and Review Notices
+
+It's possible to include frontmatter configuration for a page to set an
+expiration date for a piece of content.
+
+If the page doesn't need to be reviewed, we show a blue box with the
+last-reviewed date, when it needs review again, and the owner.
+
+![](not-expired-page.png)
+
+If the page needs to be reviewed, we show a red box saying the page might not
+be accurate.
+
+![](expired-page.png)
+
+This feature relies on JavaScript being enabled on the user's browser to
+display the relevant notices.
+
+
+## Frontmatter configuration
+
+### `last_reviewed_on` and `review_in`
+
+These attributes determine the date when the page needs to be reviewed next.
+
+```yaml
+---
+last_reviewed_on: 2018-01-18
+review_in: 6 weeks
+---
+```
+
+You can use this in combination with `owner_slack` or `default_owner_slack` to
+set an owner for the page.
+
+### `owner_slack`
+
+The Slack username or channel of the page owner. This can be used to appoint an
+individual or team as responsible for keeping the page up to date.
+
+
+## Global configuration
+
+### `owner_slack_workspace`
+
+The Slack workspace name used when linking to the Slack owner of a piece of
+content. If not provided, the owner of a piece of content (channel or user)
+won't be linked.
+
+```yaml
+owner_slack_workspace: gds
+```
+
+### `default_owner_slack`
+
+The default Slack user or channel name to show as the owner of a piece of
+content. Can be overridden using the `owner_slack` frontmatter config option.
+
+```yaml
+default_owner_slack: '#owner'
+```
+
+
+## Page API
+
+The expiry date for each page is also shown in the `/api/pages.json`
+representation of all pages.  This is used by the
+[tech-docs-notifier](https://github.com/alphagov/tech-docs-notifier) to post
+messages to Slack when pages have expired.

data/example/Gemfile

@@ -1,3 +1,4 @@
 source 'https://rubygems.org'
 
 gem 'govuk_tech_docs', path: '..'
+gem 'middleman-search', git: 'git://github.com/alphagov/middleman-search.git'

data/example/config/tech-docs.yml

@@ -41,3 +41,9 @@ github_repo: alphagov/example-repo
 
 redirects:
   /something/old.html: /index.html
+
+api_path: source/pets.yml
+
+# Optional global settings for the page review process
+owner_slack_workspace: gds
+default_owner_slack: '#2nd-line'

data/example/source/api-path.html.md

@@ -0,0 +1,7 @@
+---
+title: API /Pets
+---
+
+# API /Pets
+
+api> /pets

data/example/source/api-reference.html.md

@@ -0,0 +1,5 @@
+---
+title: Example API Petstore
+---
+
+api>

data/example/source/pets.yml

@@ -0,0 +1,106 @@
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification
+  license:
+    name: MIT
+servers:
+  - url: http://petstore.swagger.io/v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: A paged array of pets
+          headers:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    post:
+      summary: Create a pet
+      operationId: createPets
+      tags:
+        - pets
+      responses:
+        '201':
+          description: Null response
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /pets/{petId}:
+    get:
+      summary: Info for a specific pet
+      operationId: showPetById
+      tags:
+        - pets
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          description: The id of the pet to retrieve
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+components:
+  schemas:
+    Pet:
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      items:
+        $ref: "#/components/schemas/Pet"
+    Error:
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string

data/govuk_tech_docs.gemspec

@@ -32,6 +32,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency "middleman-search"
   spec.add_dependency "nokogiri"
   spec.add_dependency "redcarpet", "~> 3.3.2"
+  spec.add_dependency "openapi3_parser"
+  spec.add_dependency "pry"
 
 
   spec.add_development_dependency "bundler", "~> 1.15"

data/lib/assets/javascripts/_analytics.js

@@ -42,5 +42,17 @@
     $('.header a').on('click', linkTrackingEventHandler('topNavigationClick'));
     $('.toc a').on('click', linkTrackingEventHandler('tableOfContentsNavigationClick'));
     catchBrokenFragmentLinks();
+
+    // Borrowed from:
+    // https://github.com/alphagov/govuk_frontend_toolkit/blob/master/javascripts/govuk/analytics/analytics.js
+    window.stripPIIFromString = function (string) {
+      var EMAIL_PATTERN = /[^\s=/?&]+(?:@|%40)[^\s=/?&]+/g
+      var POSTCODE_PATTERN = /[A-PR-UWYZ][A-HJ-Z]?[0-9][0-9A-HJKMNPR-Y]?(?:[\s+]|%20)*[0-9][ABD-HJLNPQ-Z]{2}/gi
+      var DATE_PATTERN = /\d{4}(-?)\d{2}(-?)\d{2}/g
+      var stripped = string.replace(EMAIL_PATTERN, '[email]')
+      .replace(DATE_PATTERN, '[date]')
+      .replace(POSTCODE_PATTERN, '[postcode]');
+      return stripped
+    }
   });
 })(jQuery);

data/lib/assets/javascripts/_modules/collapsible-navigation.js

@@ -31,15 +31,17 @@
         var $topLevelItem = $($topLevelItems[i]);
         var $heading = $topLevelItem.find('> a');
         var $listing = $topLevelItem.find('> ul');
+        var id = 'toc-' + $heading.text().toLowerCase().replace(' ', '-');
         // Only add collapsible functionality if there are children.
         if ($listing.length == 0) {
           continue;
         }
         $topLevelItem.addClass('collapsible');
         $listing.addClass('collapsible__body')
+        .attr('id', id)
         .attr('aria-expanded', 'false');
         $heading.addClass('collapsible__heading')
-        .after('<button class="collapsible__toggle"><span class="collapsible__toggle-label">Expand ' + $heading.text() + '</span><span class="collapsible__toggle-icon" aria-hidden="true"></button>')
+        .after('<button class="collapsible__toggle" aria-controls="' + id +'"><span class="collapsible__toggle-label">Expand ' + $heading.text() + '</span><span class="collapsible__toggle-icon" aria-hidden="true"></button>')
         $topLevelItem.on('click', '.collapsible__toggle', function(e) {
           e.preventDefault();
           var $parent = $(this).parent();
@@ -51,11 +53,11 @@
     function toggleHeading($topLevelItem) {
       var isOpen = $topLevelItem.hasClass('is-open');
       var $heading = $topLevelItem.find('> a');
-      var $body = $topLevelItem.find('collapsible__body');
+      var $body = $topLevelItem.find('.collapsible__body');
       var $toggleLabel = $topLevelItem.find('.collapsible__toggle-label');
 
       $topLevelItem.toggleClass('is-open', !isOpen);
-      $body.attr('aria-expanded', isOpen ? 'true' : 'false');
+      $body.attr('aria-expanded', isOpen ? 'false' : 'true');
       $toggleLabel.text(isOpen ? 'Expand ' + $heading.text() : 'Collapse ' + $heading.text());
     }
 

data/lib/assets/javascripts/_modules/search.js

@@ -16,7 +16,9 @@
     var $searchResultsWrapper;
     var $searchResultsClose;
     var results;
-    var maxSearchEntries = 10;
+    var query;
+    var queryTimer;
+    var maxSearchEntries = 20;
 
     this.start = function start($element) {
       $searchForm = $element.find('form');
@@ -40,6 +42,7 @@
         success: function(data) {
           s.lunrData = data;
           s.lunrIndex = lunr.Index.load(s.lunrData.index);
+          replaceStopWordFilter();
           $(document).trigger('lunrIndexLoaded');
         }
       });
@@ -49,12 +52,16 @@
       // Search functionality on search text input
       $searchInput.on('input', function (e) {
         e.preventDefault();
-        var query = $(this).val();
+        query = $(this).val();
         s.search(query, function(r) {
           results = r;
           renderResults(query);
           updateTitle();
         });
+        if(window.ga) {
+          window.clearTimeout(queryTimer);
+          queryTimer = window.setTimeout(sendQueryToAnalytics, 1000);
+        }
       });
 
       // Set focus on the first search result instead of submiting the search
@@ -71,6 +78,25 @@
         $searchInput.focus();
         hideResults();
       });
+
+      // Attach analytics events to search result clicks
+      if(window.ga) {
+        $searchResults.on('click', '.search-result__title a', function() {
+          var href = $(this).attr('href');
+          ga('send', {
+            hitType: 'event',
+            eventCategory: 'Search result',
+            eventAction: 'click',
+            eventLabel: href,
+            transport: 'beacon'
+          });
+        });
+      }
+
+      // When selecting navigation link, close the search results.
+      $('.toc').on('click','a', function(e) {
+        hideResults();
+      })
     }
 
     function changeSearchLabel() {
@@ -84,7 +110,6 @@
           results.push(s.lunrData.docs[item.ref]);
         }
       });
-
       return results;
     }
 
@@ -144,9 +169,10 @@
           break;
         }
 
-        var containsMark = sentences[i].includes('mark>');
-        if (containsMark) {
-          selectedSentences.push(sentences[i].trim());
+        var sentence = sentences[i].trim();
+        var containsMark = sentence.includes('mark>');
+        if (containsMark && (selectedSentences.indexOf(sentence) == -1)) {
+          selectedSentences.push(sentence);
         }
       }
       if(selectedSentences.length > 0) {
@@ -175,6 +201,149 @@
       .attr('aria-hidden', 'true');
       $html.removeClass('has-search-results-open');
     }
+
+    function sendQueryToAnalytics() {
+      if(query === '') {
+        return;
+      }
+      var stripped = window.stripPIIFromString(query)
+      ga('send', {
+        hitType: 'event',
+        eventCategory: 'Search query',
+        eventAction: 'type',
+        eventLabel: stripped,
+        transport: 'beacon'
+      });
+    }
+
+    function replaceStopWordFilter() {
+      // Replace the default stopWordFilter as it excludes useful words like
+      // 'get'
+      // See: https://lunrjs.com/docs/stop_word_filter.js.html#line43
+      s.lunrIndex.pipeline.remove(lunr.stopWordFilter);
+      s.lunrIndex.pipeline.add(s.govukStopWorldFilter);
+    }
+
+   this.govukStopWorldFilter = lunr.generateStopWordFilter([
+      'a',
+      'able',
+      'about',
+      'across',
+      'after',
+      'all',
+      'almost',
+      'also',
+      'am',
+      'among',
+      'an',
+      'and',
+      'any',
+      'are',
+      'as',
+      'at',
+      'be',
+      'because',
+      'been',
+      'but',
+      'by',
+      'can',
+      'cannot',
+      'could',
+      'dear',
+      'did',
+      'do',
+      'does',
+      'either',
+      'else',
+      'ever',
+      'every',
+      'for',
+      'from',
+      'got',
+      'had',
+      'has',
+      'have',
+      'he',
+      'her',
+      'hers',
+      'him',
+      'his',
+      'how',
+      'however',
+      'i',
+      'if',
+      'in',
+      'into',
+      'is',
+      'it',
+      'its',
+      'just',
+      'least',
+      'let',
+      'like',
+      'likely',
+      'may',
+      'me',
+      'might',
+      'most',
+      'must',
+      'my',
+      'neither',
+      'no',
+      'nor',
+      'not',
+      'of',
+      'off',
+      'often',
+      'on',
+      'only',
+      'or',
+      'other',
+      'our',
+      'own',
+      'rather',
+      'said',
+      'say',
+      'says',
+      'she',
+      'should',
+      'since',
+      'so',
+      'some',
+      'than',
+      'that',
+      'the',
+      'their',
+      'them',
+      'then',
+      'there',
+      'these',
+      'they',
+      'this',
+      'tis',
+      'to',
+      'too',
+      'twas',
+      'us',
+      'wants',
+      'was',
+      'we',
+      'were',
+      'what',
+      'when',
+      'where',
+      'which',
+      'while',
+      'who',
+      'whom',
+      'why',
+      'will',
+      'with',
+      'would',
+      'yet',
+      'you',
+      'your'
+    ])
   };
 
   // Polyfill includes