howdoc 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c4cdda2ccd66b3c800f8711f0ea76b5220bee90496b337bccb15d1478b078b0
-  data.tar.gz: 7c2252c5adce29342f4483f3cf6529d8a9fd3f009e6b6e92747e408110d173ba
+  metadata.gz: 72edea92225be55592acd2d56c732d5d82e140193b06dc276b0c691440ff2e3f
+  data.tar.gz: 2ec1eea553ec1b5ca6e23f9f320e082367ded34280cf6701e8f284f06f1ef34c
 SHA512:
-  metadata.gz: fa0d4d38e5ee59ad0b05acd8e9db25f87e99024b9c62fd7eff1b8139a1b83712a75c68e3f540c82393658fd3febd451bf420c33bea5e69e7e6c446079574e3cf
-  data.tar.gz: 7e5147574f8c072a49e31d6f2ce9c001606f63d90604f1e7e9bc9a51257ce08ce2ae943449df76d0dbc84413766ecd58869c507a3f8c11ad32259b9a526748bf
+  metadata.gz: 9692dcfc9505fa3cf80eff5ea7a6c2dcb244619a41aa163cbab98c04a16b01bb13d82d646db46b1e98025f386a47594553abfd4b59a6e937040b555a6f9ecadb
+  data.tar.gz: 8ee1913418a639198f1134958ce9748ff83a231a5d86b8fb237675ab264d62b50ad9f5cdfd9e8433310b0c6c226bbf35ec6a21d9afd22c5eee0884b6b9042c86

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.3.0
+
+Every page now carries the menu, so a guide opened from a link is a whole page
+rather than a dead end, and a documentation set no longer needs a frame to hold
+its navigation together.
+
+- A guide leaves an empty `<nav data-howdoc-nav>`, and the index pass fills it
+  in once every guide is on disk -- a guide cannot draw a menu of guides when it
+  is written, because no other guide exists yet. A template without the
+  placeholder is left exactly as it was.
+- The same pass writes previous/next links into `<nav data-howdoc-pager>`.
+- The menu links the same guide in the other languages, matched by identifier,
+  since a translated heading gives a translated file name. Each language names
+  itself in its own language.
+- `config.group_label` now heads sections in the menu as well as the index.
+- The index carries `howdoc.index.intro` when an application translates it, so
+  the landing page can say something of its own without a hand-kept file.
+- Templates read the gem's own words through a lookup an application's I18n
+  cascade cannot answer with something unrelated.
+
 ## 0.2.0
 
 Guides are now written in every language the application publishes, from a

data/README.md

@@ -212,6 +212,39 @@ naming the language it is missing from, rather than leaving a silent hole in the
 guide. A step no language can describe is not recorded at all; a step one
 language cannot describe is left out of that language's guide only.
 
+## Navigation
+
+Every page carries the menu, and a guide links the ones before and after it:
+
+```
+public/docs/en/how_to_add_a_claim.html
+  ┌────────────┬────────────────────┐
+  │ Guides     │ 1.3. How to add a … │
+  │ EVERYDAY   │ 1. Log in …         │
+  │ 1.1 …      │ [screenshot]        │
+  │ 1.3 ●      │ ‹ Previous  Next ›   │
+  └────────────┴────────────────────┘
+```
+
+A guide cannot draw that menu when it is written: tests run in forked workers,
+each one writes its own page, and no other guide exists yet. So the guide leaves
+an empty placeholder and the index pass -- which has just read every page back
+-- fills it in:
+
+```haml
+%nav.howdoc-nav{ data: { howdoc_nav: true } }    -# the menu
+%nav.howdoc-pager{ data: { howdoc_pager: true } } -# previous / next
+```
+
+Both are optional. A template that carries neither is left exactly as it is.
+
+The menu also links the same guide in every other language the application
+publishes. Guides are matched by their identifier rather than their file name,
+because a translated heading gives a translated file name, and each language
+names itself in its own language (`howdoc.languages.<code>`).
+
+`config.group_label` heads the sections, in the menu and in the index alike.
+
 ## Templates
 
 Page chrome lives in templates, never in the code that records steps, so

data/config/locales/howdoc.en.yml

@@ -19,6 +19,11 @@ en:
       visit: Open <strong>%{url}</strong> in your browser.
     document:
       follow_steps: 'Follow these steps:'
+    languages:
+      en: English
+    pager:
+      next: Next
+      previous: Previous
     index:
       empty: No guides have been generated yet.
       title: Guides

data/config/locales/howdoc.et.yml

@@ -19,6 +19,11 @@ et:
       visit: Palun sisesta <strong>%{url}</strong> oma brauserisse.
     document:
       follow_steps: 'Palun jälgige järgnevaid samme:'
+    languages:
+      et: Eesti
+    pager:
+      next: Järgmine
+      previous: Eelmine
     index:
       empty: Ühtegi juhendit ei ole veel loodud.
       title: Juhendid

data/lib/howdoc/narrator.rb

@@ -95,6 +95,14 @@ module Howdoc
         lookup(DOCUMENTS, key, field, locale:) || default
       end
 
+      # The gem's own words -- the ones its templates print rather than the ones
+      # it narrates a step with. Looked up the safe way, so an application whose
+      # I18n cascades cannot answer an untranslated "howdoc.index.intro" with
+      # some unrelated top-level "intro" of its own.
+      def phrase(*path, locale:, default: nil)
+        lookup(*path, locale:) || default
+      end
+
       # Rails names fields after the model that owns them, which is noise to
       # anyone who does not know the schema, so the leading segment is dropped.
       def humanize_locator(locator)

data/lib/howdoc/navigation.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # The menu, and the links from one guide to the next.
+  #
+  # A guide is written the moment its test finishes, when no other guide is
+  # known yet -- tests run in forked workers and each one writes its own page --
+  # so a guide cannot draw a menu of guides. It leaves an empty <nav> instead,
+  # and this fills it in at the end of the run, when the index has just read
+  # every page back and knows what there is.
+  #
+  # Filling in rather than re-rendering: the steps a guide was made of are long
+  # gone by then, but its page is not, and this gem wrote that page. Running the
+  # pass again simply replaces what it wrote the last time.
+  #
+  # A template that carries no placeholder is left exactly as it is, so an
+  # application with its own page chrome loses nothing by not having one.
+  module Navigation
+    module_function
+
+    # Writes the menu and the pager into every guide. +by_locale+ is the sorted
+    # records the index was built from, so the menu lists the guides in the same
+    # order the index does.
+    def install(by_locale, root: Howdoc.config.root)
+      by_locale.each_value.flat_map do |records|
+        records.each_with_index.filter_map do |record, position|
+          write(record, records:, position:, by_locale:, root:)
+        end
+      end
+    end
+
+    def write(record, records:, position:, by_locale:, root:)
+      path = File.join(root, record.locale.to_s, record.filename)
+      return nil unless File.file?(path)
+
+      markup = File.read(path)
+      filled = fill(markup, :nav) { nav(record, records, by_locale) }
+      filled = fill(filled, :pager) { pager(record, records, position) }
+      return nil if filled == markup
+
+      File.write(path, filled)
+      path
+    end
+
+    # Stripped, so that filling a page in a second time leaves it exactly as the
+    # first time left it: the pass runs once per suite and again at the end of a
+    # run, and a page that grew a blank line each time would show up as changed
+    # in a repository for no reason at all.
+    def fill(markup, name)
+      markup.sub(placeholder(name)) { yield.strip }
+    end
+
+    def placeholder(name)
+      %r{<nav[^>]*data-howdoc-#{name}[^>]*>.*?</nav>}m
+    end
+
+    def nav(record, records, by_locale)
+      Templates.render(
+        'shared/html/nav.haml',
+        locale: record.locale, records:, current: record, config: Howdoc.config,
+        languages: languages(current_locale: record.locale, record:, by_locale:)
+      )
+    end
+
+    def pager(record, records, position)
+      Templates.render(
+        'shared/html/pager.haml',
+        locale: record.locale, config: Howdoc.config,
+        previous: (records[position - 1] if position.positive?),
+        next: records[position + 1]
+      )
+    end
+
+    # The same guide in the other languages the application publishes.
+    #
+    # Matched by identifier rather than by file name: a guide with a translated
+    # heading gets a translated file name, so "1.3" is the only thing the two
+    # pages are sure to have in common. A guide that was never written in the
+    # other language points at that language's index instead of nowhere.
+    def languages(current_locale:, by_locale:, record: nil)
+      ordered(by_locale.keys).map do |locale|
+        current = locale.to_s == current_locale.to_s
+
+        {
+          code: locale.to_s,
+          label: label(locale),
+          current:,
+          href: (destination(locale, record, by_locale) unless current)
+        }
+      end
+    end
+
+    def destination(locale, record, by_locale)
+      counterpart = record && counterpart(record, by_locale[locale] || [])
+
+      "../#{locale}/#{counterpart ? counterpart.filename : Registry::INDEX_FILENAME}"
+    end
+
+    def counterpart(record, records)
+      return records.find { |other| other.id == record.id } unless record.id.nil?
+
+      records.find { |other| other.permalink == record.permalink }
+    end
+
+    # A language names itself in its own language, which is how a reader who
+    # cannot read the current page still recognises the way out of it.
+    def label(locale)
+      Narrator.phrase(:languages, locale, locale:, default: locale.to_s.upcase)
+    end
+
+    def ordered(locales)
+      configured = Howdoc.config.locales&.map(&:to_s)
+      return locales.map(&:to_s).sort if configured.nil?
+
+      (configured & locales.map(&:to_s)) | locales.map(&:to_s).sort
+    end
+  end
+end

data/lib/howdoc/registry.rb

@@ -80,13 +80,23 @@ module Howdoc
       Howdoc.config.locales.to_h { |locale| [locale.to_s, found.fetch(locale.to_s, [])] }
     end
 
-    # Builds the index for every locale that produced at least one guide.
+    # Builds the index for every locale that produced at least one guide, and
+    # then writes the menu into the guides themselves: they were written one at
+    # a time, before there was a menu to draw.
     def write_indexes(root = Howdoc.config.root)
       Templates.install_assets(File.join(root, 'assets')) if Howdoc.config.install_assets
 
-      by_locale(root).map do |locale, records|
-        Writers::Index.call(locale:, records: sort(records), root:)
+      catalogue = by_locale(root).transform_values { |records| sort(records) }
+
+      written = catalogue.map do |locale, records|
+        Writers::Index.call(
+          locale:, records:, root:,
+          languages: Navigation.languages(current_locale: locale, by_locale: catalogue)
+        )
       end
+
+      Navigation.install(catalogue, root:)
+      written
     end
 
     def sort(records)

data/lib/howdoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Howdoc
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/howdoc/writers.rb

@@ -70,13 +70,13 @@ module Howdoc
 
     # Writes one index per locale, from the guides the run just produced.
     class Index
-      def self.call(locale:, records:, root: Howdoc.config.root)
+      def self.call(locale:, records:, root: Howdoc.config.root, languages: [])
         dir = File.join(root, locale.to_s)
         FileUtils.mkdir_p(dir)
 
         markup = Templates.render(
           'index/html/layout.haml',
-          locale:, records:, config: Howdoc.config
+          locale:, records:, languages:, config: Howdoc.config
         )
         path = File.join(dir, 'index.html')
         File.write(path, markup)

data/lib/howdoc.rb

@@ -13,6 +13,7 @@ require_relative 'howdoc/screenshot'
 require_relative 'howdoc/recorder'
 require_relative 'howdoc/templates'
 require_relative 'howdoc/writers'
+require_relative 'howdoc/navigation'
 require_relative 'howdoc/registry'
 
 # Generates end-user documentation from Capybara system tests.

data/templates/default/assets/howdoc.css

@@ -27,7 +27,6 @@ body.howdoc {
 
 .howdoc-document,
 .howdoc-index {
-  max-width: 52rem;
   margin: 0 auto;
   padding: 3rem 1.25rem 6rem;
 }
@@ -57,12 +56,6 @@ body.howdoc {
   padding-left: 0.25rem;
 }
 
-.howdoc-step.howdoc-arrival {
-  border-left: 3px solid var(--howdoc-accent);
-  margin-left: -1rem;
-  padding-left: 1rem;
-}
-
 .howdoc-shot {
   display: block;
   max-width: 100%;
@@ -103,7 +96,114 @@ body.howdoc {
   text-decoration: underline;
 }
 
+/* The menu sits beside the page it belongs to, and above it when there is no
+   room beside. A guide written before the index pass has an empty menu, and an
+   empty menu is no menu at all. */
+.howdoc-nav:empty,
+.howdoc-pager:empty {
+  display: none;
+}
+
+.howdoc-nav {
+  padding: 1.5rem 1.25rem;
+  border-bottom: 1px solid var(--howdoc-rule);
+}
+
+@media (min-width: 60rem) {
+  body.howdoc {
+    display: grid;
+    grid-template-columns: 19rem minmax(0, 1fr);
+    align-items: start;
+  }
+
+  .howdoc-nav {
+    position: sticky;
+    top: 0;
+    max-height: 100vh;
+    overflow-y: auto;
+    padding: 2rem 1.25rem 3rem;
+    border-right: 1px solid var(--howdoc-rule);
+    border-bottom: 0;
+  }
+}
+
+.howdoc-nav-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.howdoc-nav-home {
+  color: var(--howdoc-fg);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.howdoc-languages {
+  display: flex;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-size: 0.85rem;
+}
+
+.howdoc-language a {
+  color: var(--howdoc-accent);
+  text-decoration: none;
+}
+
+.howdoc-language.howdoc-current {
+  color: var(--howdoc-muted);
+}
+
+.howdoc-toc-entry.howdoc-current > a {
+  color: var(--howdoc-fg);
+  font-weight: 600;
+}
+
+.howdoc-pager {
+  display: flex;
+  gap: 1rem;
+  margin-top: 3rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--howdoc-rule);
+}
+
+.howdoc-pager-link {
+  display: flex;
+  flex: 1 1 0;
+  flex-direction: column;
+  gap: 0.25rem;
+  padding: 0.9rem 1rem;
+  border: 1px solid var(--howdoc-rule);
+  border-radius: 8px;
+  text-decoration: none;
+}
+
+.howdoc-pager-next {
+  margin-left: auto;
+  text-align: right;
+}
+
+.howdoc-pager-label {
+  color: var(--howdoc-muted);
+  font-size: 0.8rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.howdoc-pager-heading {
+  color: var(--howdoc-accent);
+}
+
 @media print {
+  .howdoc-nav,
+  .howdoc-pager {
+    display: none;
+  }
+
   .howdoc-shot {
     box-shadow: none;
   }

data/templates/default/document/html/layout.haml

@@ -6,11 +6,16 @@
     %title= @document.heading
     %link{ rel: 'stylesheet', href: '../assets/howdoc.css' }
   %body.howdoc
+    -# Empty on purpose: the index pass writes the menu and the pager in here
+    -# once it knows what the other guides are. A page is a whole page either
+    -# way, so a guide opened straight from a link is never a dead end.
+    %nav.howdoc-nav{ data: { howdoc_nav: true } }
     %main.howdoc-document
       %h1= @document.heading
       - unless @document.intro.to_s.strip.empty?
         .howdoc-intro!= @document.intro
-      %p.howdoc-lede= I18n.t('howdoc.document.follow_steps', locale: @document.locale)
+      %p.howdoc-lede= Howdoc::Narrator.phrase(:document, :follow_steps, locale: @document.locale)
       %ol.howdoc-steps
         - @document.steps.reject(&:empty?).each do |step|
           != render('document/html/step.haml', step: step)
+      %nav.howdoc-pager{ data: { howdoc_pager: true } }

data/templates/default/index/html/layout.haml

@@ -3,20 +3,15 @@
   %head
     %meta{ charset: 'utf-8' }
     %meta{ name: 'viewport', content: 'width=device-width, initial-scale=1' }
-    %title= I18n.t('howdoc.index.title', locale: @locale)
+    %title= Howdoc::Narrator.phrase(:index, :title, locale: @locale)
     %link{ rel: 'stylesheet', href: '../assets/howdoc.css' }
   %body.howdoc
+    -# The index knows every guide already, so it draws the menu itself.
+    != render('shared/html/nav.haml', current: nil)
     %main.howdoc-index
-      %h1= I18n.t('howdoc.index.title', locale: @locale)
+      %h1= Howdoc::Narrator.phrase(:index, :title, locale: @locale)
+      - intro = Howdoc::Narrator.phrase(:index, :intro, locale: @locale)
+      - if intro
+        .howdoc-intro!= intro
       - if @records.empty?
-        %p= I18n.t('howdoc.index.empty', locale: @locale)
-      - else
-        %ul.howdoc-toc
-          - previous_group = nil
-          - @records.each do |record|
-            - group = @config.group_label.call(record)
-            - if group && group != previous_group
-              %li.howdoc-toc-group= group
-              - previous_group = group
-            %li.howdoc-toc-entry
-              %a{ href: "./#{record.filename}" }= record.heading
+        %p= Howdoc::Narrator.phrase(:index, :empty, locale: @locale)

data/templates/default/shared/html/nav.haml

@@ -0,0 +1,25 @@
+-# The menu every page carries. A guide cannot draw this when it is written --
+-# no other guide exists yet -- so a guide leaves the empty <nav> below and the
+-# index pass fills it in once every guide is on disk. The index renders it
+-# directly, because by then it knows.
+%nav.howdoc-nav{ data: { howdoc_nav: true } }
+  .howdoc-nav-head
+    %a.howdoc-nav-home{ href: './index.html' }= Howdoc::Narrator.phrase(:index, :title, locale: @locale)
+    - if @languages.size > 1
+      %ul.howdoc-languages
+        - @languages.each do |language|
+          %li.howdoc-language{ class: ('howdoc-current' if language[:current]) }
+            - if language[:href]
+              %a{ href: language[:href], lang: language[:code] }= language[:label]
+            - else
+              %span{ lang: language[:code] }= language[:label]
+  %ul.howdoc-toc
+    - previous_group = nil
+    - @records.each do |record|
+      - group = @config.group_label.call(record)
+      - if group && group != previous_group
+        %li.howdoc-toc-group= group
+        - previous_group = group
+      - current = @current && record.filename == @current.filename
+      %li.howdoc-toc-entry{ class: ('howdoc-current' if current) }
+        %a{ href: "./#{record.filename}", 'aria-current': (current ? 'page' : nil) }= record.heading

data/templates/default/shared/html/pager.haml

@@ -0,0 +1,11 @@
+-# Step-by-step guides are read in order, so each one says what comes next.
+-# Written by the same pass as the menu, for the same reason.
+%nav.howdoc-pager{ data: { howdoc_pager: true } }
+  - if @previous
+    %a.howdoc-pager-link.howdoc-pager-previous{ href: "./#{@previous.filename}", rel: 'prev' }
+      %span.howdoc-pager-label= Howdoc::Narrator.phrase(:pager, :previous, locale: @locale)
+      %span.howdoc-pager-heading= @previous.heading
+  - if @next
+    %a.howdoc-pager-link.howdoc-pager-next{ href: "./#{@next.filename}", rel: 'next' }
+      %span.howdoc-pager-label= Howdoc::Narrator.phrase(:pager, :next, locale: @locale)
+      %span.howdoc-pager-heading= @next.heading

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howdoc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Priit Tark
@@ -61,6 +61,7 @@ files:
 - lib/howdoc/edition.rb
 - lib/howdoc/minitest.rb
 - lib/howdoc/narrator.rb
+- lib/howdoc/navigation.rb
 - lib/howdoc/recorder.rb
 - lib/howdoc/registry.rb
 - lib/howdoc/screenshot.rb
@@ -73,6 +74,8 @@ files:
 - templates/default/document/html/layout.haml
 - templates/default/document/html/step.haml
 - templates/default/index/html/layout.haml
+- templates/default/shared/html/nav.haml
+- templates/default/shared/html/pager.haml
 homepage: https://github.com/priit/howdoc
 licenses:
 - MIT