rspec-documentation 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da04d0bb8e452ebcf2858bff1c50b704099bd28ef683e4bd18759952195b8543
-  data.tar.gz: db7bb967b2c35fd6b972f3ff295561e1731ade67d07c9d6132f797504d855cc3
+  metadata.gz: 8ce43727fba18b77d655b8ba4dc96b66b730823d4c44603a17d3033f70092daa
+  data.tar.gz: a53de33b4779cca033dfaa87eea7e60f473af09db986117c9a3d98cd9417d874
 SHA512:
-  metadata.gz: 733742f420606fab2d6cb27ab9c180e2c30260184e903314337ae994453de0d3863e00df34407f613103d9bef55697fea044fde7e436018e50fdf39a68f41e02
-  data.tar.gz: 4271936018c835d3e6af24d8a1f5329a3b229b89528d53e04cba2a44e42b459f49a4fde648820a9e1e9a0710fe692db891ecc866d5a5a9767f7ad9098c30f330
+  metadata.gz: 7e44facb6a2ece7170e6111ced783f9e4a48780f478afbd257c6f30552816f6fcb22ab6733914f26c68168a71331f77c777f770e0e343c0301ad2be23855602e
+  data.tar.gz: ac708a5ee5336cb2c2aa9282704a94bb0d6d1f8120293af0cbc84e63d3914d88de25fdff7b942a1759f8f7a8d17e8252398ed3ba06d771c77023fa206bb42bc1

data/.rubocop.yml

@@ -1,4 +1,5 @@
 require:
+- 'rubocop-rspec-documentation'
 - 'rubocop-rake'
 - 'rubocop-rspec'
 

data/Gemfile

@@ -15,4 +15,5 @@ gem 'rspec-its', '~> 1.3'
 gem 'rubocop', '~> 1.52'
 gem 'rubocop-rake', '~> 0.6.0'
 gem 'rubocop-rspec', '~> 2.22'
+gem 'rubocop-rspec-documentation', require: false
 gem 'strong_versions', '~> 0.4.5'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-documentation (0.0.7)
+    rspec-documentation (0.0.8)
       htmlbeautifier (~> 1.4)
       kramdown (~> 2.4)
       kramdown-parser-gfm (~> 1.1)
@@ -19,7 +19,7 @@ GEM
     devpack (0.4.1)
     diff-lcs (1.5.0)
     htmlbeautifier (1.4.2)
-    i18n (1.13.0)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
     kramdown (2.4.0)
@@ -31,15 +31,16 @@ GEM
     paint (2.3.0)
     paintbrush (0.1.3)
     parallel (1.23.0)
-    parser (3.2.2.1)
+    parser (3.2.2.3)
       ast (~> 2.4.1)
-    racc (1.6.2)
+      racc
+    racc (1.7.0)
     rainbow (3.1.1)
     rake (13.0.6)
     redcarpet (3.6.0)
-    regexp_parser (2.8.0)
+    regexp_parser (2.8.1)
     rexml (3.2.5)
-    rouge (4.1.1)
+    rouge (4.1.2)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -49,8 +50,8 @@ GEM
     rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
-    rspec-file_fixtures (0.1.6)
-      rspec (~> 3.0)
+    rspec-file_fixtures (0.1.7)
+      rspec (~> 3.12)
     rspec-its (1.3.0)
       rspec-core (>= 3.0.0)
       rspec-expectations (>= 3.0.0)
@@ -58,10 +59,10 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)
-    rubocop (1.52.0)
+    rubocop (1.52.1)
       json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.2.2.3)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
@@ -80,6 +81,9 @@ GEM
       rubocop (~> 1.33)
       rubocop-capybara (~> 2.17)
       rubocop-factory_bot (~> 2.22)
+    rubocop-rspec-documentation (0.0.1)
+      rspec-documentation (~> 0.0.7)
+      rubocop (~> 1.52)
     ruby-progressbar (1.13.0)
     strong_versions (0.4.5)
       i18n (>= 0.5)
@@ -100,6 +104,7 @@ DEPENDENCIES
   rubocop (~> 1.52)
   rubocop-rake (~> 0.6.0)
   rubocop-rspec (~> 2.22)
+  rubocop-rspec-documentation
   strong_versions (~> 0.4.5)
 
 BUNDLED WITH

data/exe/rspec-documentation

@@ -3,6 +3,21 @@
 
 require_relative '../lib/rspec/documentation'
 
+require 'optparse'
+
+options = {}
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: rspec-documentation [options]'
+  opts.on('-F', '--fail-fast', 'Abort the run after the first failure.') { |val| options[:fail_fast] = val if val }
+  opts.on('-b', '--backtrace', 'Enable full backtrace.') { |val| options[:full_backtrace] = val if val }
+end.parse!
+
+RSpec::Documentation.configure do |config|
+  config.fail_fast = options[:fail_fast] if options.key?(:fail_fast)
+  config.full_backtrace = options[:full_backtrace] if options.key?(:full_backtrace)
+end
+
 documentation = RSpec::Documentation.generate_documentation
 
 exit 1 if documentation.failed?

data/lib/rspec/documentation/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Documentation
-    VERSION = '0.0.7'
+    VERSION = '0.0.8'
   end
 end

data/lib/rspec_documentation/configuration.rb

@@ -4,12 +4,16 @@ module RSpecDocumentation
   # Configures the rspec-documentation gem, allows setting a context that makes values available to each example.
   class Configuration
     attr_reader :hooks
-    attr_accessor :consistent_height, :max_height
+    attr_accessor :consistent_height, :max_height, :fail_fast, :full_backtrace, :table_of_contents, :index_search
 
     def initialize
       @context_defined = false
       @consistent_height = false
       @max_height = '30rem'
+      @fail_fast = false
+      @full_backtrace = false
+      @table_of_contents = true
+      @index_search = true
       @hooks = {}
     end
 

data/lib/rspec_documentation/document.rb

@@ -18,6 +18,7 @@ module RSpecDocumentation
 
     def render
       parsed_document.execute_and_substitute_examples!
+
       if parsed_document.failures.empty?
         RSpecDocumentation.template('layout').result(binding)
       else
@@ -63,11 +64,17 @@ module RSpecDocumentation
     attr_reader :document, :path
 
     def parsed_document
-      @parsed_document ||= ParsedDocument.new(document, path: path)
+      @parsed_document ||= ParsedDocument.new(with_table_of_contents(document), path: path)
     end
 
     def gem_spec
       @gem_spec ||= Gem::Specification.load(Pathname.new(Dir.pwd).glob('*.gemspec').first.to_s)
     end
+
+    def with_table_of_contents(markdown)
+      return markdown unless RSpecDocumentation.configuration.table_of_contents
+
+      ['* TOC', '{:toc}', markdown].join("\n")
+    end
   end
 end

data/lib/rspec_documentation/documentation.rb

@@ -22,11 +22,14 @@ module RSpecDocumentation
       @failed || !page_collection.failures.empty?
     end
 
+    def page_collection
+      @page_collection ||= RSpecDocumentation::PageCollection.new(page_paths: page_paths)
+    end
+
     private
 
     def require_spec_helper
-      path = pwd.join('rspec-documentation/spec_helper.rb')
-      require path if path.file?
+      require Util.spec_helper_path if Util.spec_helper_path.file?
     end
 
     # Ensure `__rspec_documentation` shared context is always defined.
@@ -74,10 +77,6 @@ module RSpecDocumentation
       @page_paths ||= pwd.join('rspec-documentation/pages').glob('**/*.md')
     end
 
-    def page_collection
-      @page_collection ||= RSpecDocumentation::PageCollection.new(page_paths: page_paths)
-    end
-
     def pwd
       @pwd ||= Pathname.new(Dir.pwd)
     end

data/lib/rspec_documentation/kramdown_html_converter.rb

@@ -9,6 +9,19 @@ module Kramdown
         element.attr['class'] ||= 'rspec-documentation-table table'
         super
       end
+
+      def convert_header(element, indent)
+        [
+          '<div class="heading">',
+          super,
+          "<a class='heading-anchor' href='##{element.attr['id']}'>#{link_icon}</a>",
+          '</div>'
+        ].join
+      end
+
+      def link_icon
+        @link_icon ||= RSpecDocumentation.template(:link, :svg).result
+      end
     end
   end
 end

data/lib/rspec_documentation/page_collection.rb

@@ -6,6 +6,8 @@ module RSpecDocumentation
   class PageCollection
     attr_reader :failures, :page_paths
 
+    include Paintbrush
+
     def initialize(page_paths:)
       @page_paths = page_paths.sort_by(&:to_s)
       @buffer = {}
@@ -16,6 +18,7 @@ module RSpecDocumentation
       page_paths.zip(documents).each do |path, document|
         buffer[bundle_path_for(path)] = document.render
         failures.concat(document.failures)
+        break if RSpecDocumentation.configuration.fail_fast && !failures.empty?
       end
     end
 

data/lib/rspec_documentation/page_tree.rb

@@ -48,15 +48,15 @@ module RSpecDocumentation
       nodes.last == '<ol>' ? nodes.pop : nodes.push('</ol>')
     end
 
-    def build_tree(branch: structure, depth: 0)
-      normalized_paths.each do |path|
+    def build_tree(paths: normalized_paths, branch: structure, depth: 0)
+      paths.each do |path|
         first, second, *rest = path_segments(path: path, depth: depth)
         next if second.nil?
 
         branch[first] ||= {}
         branch[first][:children] ||= Set.new
         branch[first][:children].add(second)
-        build_tree(branch: branch[first], depth: depth + 1)
+        build_tree(paths: filtered_paths(path), branch: branch[first], depth: depth + 1)
       end
     end
 
@@ -74,6 +74,10 @@ module RSpecDocumentation
       end
     end
 
+    def filtered_paths(path)
+      normalized_paths.select { |normalized_path| normalized_path.to_s.start_with?(path.sub_ext('').to_s) }
+    end
+
     def page_tree_node(path:, child:)
       PageTreeElement.new(path: path, child: child, current_path: current_path).node
     end

data/lib/rspec_documentation/page_tree_element.rb

@@ -44,7 +44,7 @@ module RSpecDocumentation
 
     def li_open
       "<li id='#{Util.path_id(path.join(child))}' #{active_class} data-list-item-id='##{path_id}' " \
-        "data-parent-id='##{parent_path_id}'>"
+        "data-search-tokens='#{Util.tokens(child).to_json}' data-parent-id='##{parent_path_id}'>"
     end
 
     def link

data/lib/rspec_documentation/parsed_document.rb

@@ -5,8 +5,16 @@ module RSpecDocumentation
   class ParsedDocument
     attr_reader :failures
 
+    include Paintbrush
+
     def initialize(document, path:)
-      @document = Kramdown::Document.new(document, input: 'GFM', syntax_highlighter: 'rouge')
+      @document = Kramdown::Document.new(
+        document,
+        toc_levels: 2...6,
+        input: 'GFM',
+        syntax_highlighter: 'rouge',
+        auto_ids: true
+      )
       @path = path
       @failures = []
     end
@@ -16,11 +24,11 @@ module RSpecDocumentation
     end
 
     def execute_and_substitute_examples!
+      print_empty if specs.empty?
       specs.each do |spec|
         spec.run
-        next failures << spec.failure unless spec.failure.nil?
-
-        spec.parent.children[spec.index] = spec_element(spec)
+        process_outcome(spec)
+        break if RSpecDocumentation.configuration.fail_fast && !failures.empty?
       end
     end
 
@@ -65,8 +73,34 @@ module RSpecDocumentation
       end
     end
 
+    def process_outcome(spec)
+      if spec.failure.nil?
+        print_success(spec)
+        spec.parent.children[spec.index] = spec_element(spec)
+      else
+        print_failure(spec)
+        failures << spec.failure
+      end
+    end
+
+    def relative_path
+      path.relative_path_from(Util.base_dir)
+    end
+
     def report_error(spec)
       $stderr.write(spec.failure.message)
     end
+
+    def print_empty
+      warn(paintbrush { cyan "    #{relative_path}" })
+    end
+
+    def print_success(spec)
+      warn(paintbrush { green "    #{relative_path}:#{spec.location}" })
+    end
+
+    def print_failure(spec)
+      warn(paintbrush { red "    #{relative_path}:#{spec.location}" })
+    end
   end
 end

data/lib/rspec_documentation/project_initialization.rb

@@ -9,6 +9,7 @@ module RSpecDocumentation
       print_welcome
       create_base_dir
       create_sample_files
+      create_spec_helper
       print_initialization_complete
     end
 
@@ -31,6 +32,13 @@ module RSpecDocumentation
       end
     end
 
+    def create_spec_helper
+      return if Util.spec_helper_path.exist?
+
+      Util.spec_helper_path.write(RSpecDocumentation.template(:spec_helper, :rb).result)
+      print_created(Util.spec_helper_path)
+    end
+
     def print_created(path)
       warn(paintbrush { "   #{green_b 'create'} #{cyan path.relative_path_from(pwd)}" })
     end

data/lib/rspec_documentation/rspec/failure.rb

@@ -39,7 +39,7 @@ module RSpecDocumentation
 
       def formatted_backtrace
         cause.backtrace
-             &.take_while { |line| line.start_with?(Dir.pwd) }
+             &.take_while { |line| RSpecDocumentation.configuration.full_backtrace || line.start_with?(Dir.pwd) }
              &.map { |line| paintbrush { red "    #{line.sub("#{Dir.pwd}/", '')}" } }
              &.join("\n")
       end

data/lib/rspec_documentation/util.rb

@@ -14,6 +14,10 @@ module RSpecDocumentation
       bundle_dir.join('index.html')
     end
 
+    def self.spec_helper_path
+      root_dir.join('rspec-documentation/spec_helper.rb')
+    end
+
     def self.base_dir
       root_dir.join('rspec-documentation', 'pages')
     end
@@ -29,7 +33,11 @@ module RSpecDocumentation
     end
 
     def self.label(path)
-      Pathname.new(path).basename.sub_ext('').sub(ORDERING_PREFIX_REGEXP, '')
+      Pathname.new(path).basename.sub_ext('').sub(ORDERING_PREFIX_REGEXP, '').to_s
+    end
+
+    def self.tokens(path)
+      label(path).downcase.split
     end
 
     def self.path_id(path)
@@ -52,7 +60,9 @@ module RSpecDocumentation
     end
 
     def self.normalized_filename(path)
-      path.to_s.gsub(' ', '-').downcase.sub(ORDERING_PREFIX_REGEXP, '')
+      path.split.map do |segment|
+        segment.to_s.gsub(' ', '-').downcase.sub(ORDERING_PREFIX_REGEXP, '')
+      end.join('/')
     end
   end
 end

data/lib/templates/layout.css.erb

@@ -35,6 +35,35 @@
   }
 }
 
+[data-bs-theme="dark"] .table-of-contents-wrapper {
+  border-color: #444242;
+  background-color: #4e4e4e55;
+}
+
+[data-bs-theme="dark"] .table-of-contents-wrapper .title {
+  border-color: #444242;
+}
+
+[data-bs-theme="dark"] table.rspec-documentation-table td, [data-bs-theme="dark"] table.rspec-documentation-table th {
+  border: 1px solid #4e4e4e;
+}
+
+[data-bs-theme="dark"] table.rspec-documentation-table tr:hover td {
+  background-color: #325d8833;
+}
+
+[data-bs-theme="dark"] .header-wrapper {
+  background-color: #212121;
+}
+
+[data-bs-theme="dark"] .form-control {
+  color: #b2b2b2;
+}
+
+[data-bs-theme="dark"] input.form-control::placeholder {
+  color: #999;
+}
+
 body {
   opacity: 0;
   animation: fade-in ease-in 1;
@@ -45,6 +74,11 @@ body {
 
 .header-wrapper {
   background-color: #fff;
+  z-index: 100000;
+}
+
+table.rspec-documentation-table tr:hover td {
+  background-color: #8a8d9124;
 }
 
 table.rspec-documentation-table td, table.rspec-documentation-table th {
@@ -52,12 +86,68 @@ table.rspec-documentation-table td, table.rspec-documentation-table th {
   padding: 0.5rem 1rem;
 }
 
-[data-bs-theme="dark"] table.rspec-documentation-table td, [data-bs-theme="dark"] table.rspec-documentation-table th {
-  border: 1px solid #4e4e4e;
+.index-search {
+  margin-bottom: 1rem;
 }
 
-[data-bs-theme="dark"] .header-wrapper {
-  background-color: #212121;
+.page-tree li.search-active {
+  list-style: circle;
+  list-style-color: green;
+}
+
+.table-of-contents-wrapper {
+  position: relative;
+  padding: 0.4rem 0.8rem;
+  background-color: #c7c7c729;
+  display: inline-block;
+  float: right;
+  margin-left: 1rem;
+  margin-bottom: 0.4rem;
+  border-style: solid;
+  border-width: 1px;
+  border-radius: 10px;
+  border-color: #cfcfcf;
+}
+
+.table-of-contents-wrapper .title {
+  text-align: center;
+  border-bottom: 1px solid #cfcfcf;
+  margin-bottom: 0.2rem;
+  padding-bottom: 0.2rem;
+  font-weight: bold;
+}
+
+#markdown-toc {
+  list-style: disc;
+  line-height: 1.8rem;
+  padding: 0;
+  margin-bottom: 0;
+  padding-left: 1rem;
+}
+
+#markdown-toc ul {
+  padding-left: 1rem;
+}
+
+.heading-anchor {
+  padding: 0.2rem;
+  vertical-align: middle;
+  display: inline-block;
+  padding-bottom: 0.4rem;
+  scroll-padding-top: 5rem;
+}
+
+.heading-anchor svg {
+  width: 1rem;
+  height: 1rem;
+}
+
+.heading-anchor svg path {
+  fill: #7ac0f8;
+}
+
+#markdown-toc li a {
+  text-decoration: none;
 }
 
 .theme-switcher {
@@ -88,8 +178,20 @@ h1.title a {
   text-decoration: none;
 }
 
+.content h1, .content h2, .content h3, .content h4, .content h5, .content h6 {
+  display: inline-block;
+  scroll-margin-top: 6rem;
+}
+
+.heading-anchor {
+  font-size: 0.8rem;
+  text-decoration: none;
+  color: rgb(122,192,248);
+}
+
 .code {
   font-family: monospace;
+  font-size: 0.9rem;
   max-height: <%= RSpecDocumentation.configuration.max_height %>;
   overflow-y: auto;
 }

data/lib/templates/layout.html.erb

@@ -1,6 +1,7 @@
 <html>
   <head>
     <meta charset="utf-8" />
+    <title><%= title %></title>
     <%= RSpecDocumentation.template(:stylesheet_links).result(binding) %>
     <%= RSpecDocumentation.hook(:after_head) %>
   </head>
@@ -15,11 +16,19 @@
 
       <div class="row flex-nowrap">
         <div class="col-sm-2 fs-6 mt-1 ms-3 me-3">
-          <ol class="page-tree hidden position-fixed">
-            <% page_tree.elements.each do |element| %>
-              <%= element %>
+          <div class="position-fixed">
+            <% if RSpecDocumentation.configuration.index_search %>
+            <div class="index-search">
+              <input type="text" class="index-search-field form-control" placeholder="Search (Ctrl+/)" />
+            </div>
             <% end %>
-          </ol>
+
+            <ol class="page-tree hidden">
+              <% page_tree.elements.each do |element| %>
+                <%= element %>
+              <% end %>
+            </ol>
+          </div>
         </div>
 
         <%= RSpecDocumentation.hook(:before_content) %>

data/lib/templates/layout.js.erb

@@ -1,10 +1,11 @@
 <%= RSpecDocumentation.template('bootstrap', :js).result %>
 
 (() => {
-  const initPageTree = () => {
-    const pageTree = document.querySelector('.page-tree');
+  const pageTree = document.querySelector('.page-tree');
+  const getParentElement = (element) => document.querySelector(element.dataset.parentId);
+  const pageSearchTokens = {};
 
-    const getParentElement = (element) => document.querySelector(element.dataset.parentId);
+  const initPageTree = () => {
     const isRootElement = (element) => !getParentElement(element);
     const isChildActive = (element) => !!element.querySelectorAll('.active').length;
     const isSiblingActive = (element) => !!getParentElement(element).querySelectorAll('.active').length;
@@ -22,7 +23,14 @@
     const visibilityCriteria = [isRootElement, isSelfOrParentActive, isChildActive, isSiblingActive];
 
     pageTree.querySelectorAll('li').forEach((element) => {
-      if (!visibilityCriteria.some((criterion) => criterion(element))) element.classList.add('d-none');
+      element.classList.remove('search-active');
+      pageSearchTokens[element.id] = JSON.parse(element.dataset.searchTokens);
+
+      if (!visibilityCriteria.some((criterion) => criterion(element))) {
+        element.classList.add('d-none');
+      } else {
+        element.classList.remove('d-none');
+      }
     });
     pageTree.classList.remove('hidden');
   };
@@ -62,6 +70,80 @@
     });
   });
 
+  initTableOfContents = () => {
+    const tableOfContents = document.querySelector('#markdown-toc');
+
+    if (!tableOfContents) return;
+
+    const wrapper = document.createElement('div');
+    const content = document.querySelector('div.content');
+    const title = document.createElement('div');
+
+    title.append('Links');
+    title.classList.add('title');
+    wrapper.append(title);
+    wrapper.append(tableOfContents);
+    wrapper.classList.add('table-of-contents-wrapper');
+    content.prepend(wrapper);
+  };
+
+  initIndexSearch = () => {
+    const indexSearch = document.querySelector('.index-search');
+    const indexSearchField = indexSearch.querySelector('input');
+    const getQueryTokens = () => indexSearchField.value.toLowerCase().split(/\s+/);
+
+    indexSearch.addEventListener('keyup', (ev) => {
+      if (ev.keyCode === 13) {
+        const anchor = pageTree.querySelector('li.search-active a');
+        if (anchor) window.location = anchor.href;
+      } else {
+        searchIndex(getQueryTokens());
+      }
+    });
+    indexSearch.addEventListener('change', (ev) => searchIndex(getQueryTokens()));
+
+    document.addEventListener('keydown', (ev) => {
+      if (ev.ctrlKey && ev.keyCode === 191) {
+        ev.preventDefault();
+        indexSearchField.focus();
+      }
+    });
+
+    searchIndex = (searchTokens) => {
+      if (!searchTokens.every((searchToken) => searchToken)) {
+        initPageTree();
+        return;
+      }
+
+      const unhideRecursively = (element) => {
+        const parentElement = getParentElement(element);
+
+        element.classList.remove('d-none');
+
+        if (parentElement) unhideRecursively(parentElement);
+      };
+
+      const getMatchingTokens = (tokens) => {
+        const anyMatchingTokens = (token) => tokens.some((expectedToken) => expectedToken.includes(token))
+        return searchTokens.filter((token) => anyMatchingTokens(token));
+      };
+
+      pageTree.querySelectorAll('li').forEach((element) => {
+        const elementSearchTokens = pageSearchTokens[element.id];
+
+        if (getMatchingTokens(elementSearchTokens).length) {
+          element.classList.add('search-active');
+          unhideRecursively(element);
+        } else {
+          element.classList.add('d-none');
+          element.classList.remove('search-active');
+        }
+      });
+    };
+  };
+
   initPageTree();
   initThemeSwitcher();
+  initTableOfContents();
+  initIndexSearch();
 })();

data/lib/templates/link.svg.erb

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8"?><svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 122.88 122.88" style="enable-background:new 0 0 122.88 122.88" xml:space="preserve"><g><path d="M37.49,53.69c1.25-1.25,3.27-1.25,4.51,0c1.25,1.25,1.25,3.27,0,4.51L6.61,93.6l22.67,22.67l0,0l35.44-35.44 c1.25-1.25,3.27-1.25,4.51,0c1.25,1.25,1.25,3.27,0,4.52L33.4,121.18v0l-0.01-0.01l-0.01,0.01c-1.14,1.14-2.62,1.7-4.11,1.7 c-1.38,0-2.76-0.49-3.86-1.47c-0.09-0.07-0.17-0.15-0.26-0.23l0,0L1.7,97.72C0.57,96.58,0,95.09,0,93.6c0-1.49,0.57-2.98,1.7-4.12 L37.49,53.69L37.49,53.69z M77.12,41.24c1.25-1.25,3.27-1.25,4.52,0c1.25,1.25,1.25,3.27,0,4.52l-31.4,31.4 c-1.25,1.25-3.27,1.25-4.51,0c-1.25-1.25-1.25-3.27,0-4.51L77.12,41.24L77.12,41.24z M85.6,68.98c-1.25,1.25-3.27,1.25-4.52,0 c-1.25-1.25-1.25-3.27,0-4.52l35.19-35.19L93.6,6.61L58.48,41.73c-1.25,1.25-3.27,1.25-4.51,0c-1.25-1.25-1.25-3.27,0-4.51 L89.48,1.7C90.62,0.57,92.11,0,93.6,0c1.49,0,2.98,0.57,4.12,1.7l23.46,23.46l0,0l-0.01,0.01l0.01,0.01 c1.14,1.14,1.7,2.62,1.7,4.11c0,1.49-0.57,2.98-1.7,4.12l0,0L85.6,68.98L85.6,68.98z"/></g></svg>

data/lib/templates/modal_spec.html.erb

@@ -2,14 +2,14 @@
   <div class="modal-dialog modal-xl" id="modal-dialog-<%= element_id %>">
     <div class="modal-content">
       <div class="modal-header">
-        <h5 class="modal-title" id="modal-<%= element_id %>-side-by-side-label">Side-by-side view</h5>
+        <h5 class="no_toc modal-title" id="modal-<%= element_id %>-side-by-side-label">Side-by-side view</h5>
         <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
       </div>
       <div class="modal-body">
         <div class="container p-3">
           <div class="row border">
             <div class="col border">
-              <h5>Spec</h5>
+              <h5 class="no_toc">Spec</h5>
               <hr/>
               <div class="p-3 mb-5 code highlight">
                 <%= code_source %>
@@ -18,7 +18,7 @@
 
             <% unless prettified_output.nil? %>
             <div class="col border">
-              <h5>Output</h5>
+              <h5 class="no_toc">Output</h5>
               <hr/>
               <div class="p-3 mb-5 code highlight">
                 <%= prettified_output %>
@@ -28,9 +28,9 @@
 
             <div class="col border">
               <% if prettified_output.nil? %>
-                <h5>Output</h5>
+                <h5 class="no_toc">Output</h5>
               <% else %>
-                <h5>Rendered Output</h5>
+                <h5 class="no_toc">Rendered Output</h5>
               <% end %>
               <hr/>
               <div class="p-3 mb-5 border <%= render_raw? ? nil : 'code highlight' %>">

data/lib/templates/spec_helper.rb.erb

@@ -0,0 +1,25 @@
+RSpec::Documentation.configure do |config|
+  # Force example tabs to have a consistent height to prevent content jumping.
+  # config.consistent_height = <%= RSpecDocumentation.configuration.consistent_height.inspect %>
+
+  # Set a maximum height for example tabs. Tabs will scroll if content exceeds this value.
+  # config.max_height = <%= RSpecDocumentation.configuration.max_height.inspect %>
+
+  # Enable or disable the table of contents for each page. This renders a list of all headings in
+  # the page, except the main heading.
+  # config.table_of_contents = <%= RSpecDocumentation.configuration.table_of_contents.inspect %>
+
+  # Enable or disable the index search above the navigation tree.
+  # config.index_search = <%= RSpecDocumentation.configuration.index_search.inspect %>
+
+  config.context do
+    # Define global context here, e.g. add some `let` blocks to make them available in every example.
+    #
+    # let(:foo) { 'bar' }
+  end
+end
+
+RSpec.configure do |config|
+  # Define RSpec configuration here.
+  # Note that your main `spec/spec_helper.rb` is not loaded unless you require it in this file.
+end

data/lib/templates/tabbed_spec.html.erb

@@ -5,7 +5,7 @@
   <ul class="nav nav-tabs" id="html-tabs-<%= element_id %>" role="tablist">
 
     <li class="nav-item" role="presentation">
-      <button class="nav-link active"
+      <button class="no_toc nav-link active"
               id="code-source-<%= element_id %>-tab"
               data-bs-toggle="tab"
               data-bs-target="#code-source-<%= element_id %>"
@@ -17,7 +17,7 @@
 
     <% unless prettified_output.nil? %>
     <li class="nav-item" role="presentation">
-      <button class="nav-link"
+      <button class="no_toc nav-link"
               id="html-source-<%= element_id %>-tab"
               data-bs-toggle="tab"
               data-bs-target="#html-source-<%= element_id %>"
@@ -29,7 +29,7 @@
     <% end %>
 
     <li class="nav-item" role="presentation">
-      <button class="nav-link"
+      <button class="no_toc nav-link"
               id="rendered-<%= element_id %>-tab"
               data-bs-toggle="tab"
               data-bs-target="#rendered-<%= element_id %>"
@@ -40,7 +40,7 @@
     </li>
 
     <li class="nav-item bs-auto ms-auto mb-2">
-      <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#modal-<%= element_id %>-side-by-side">
+      <button type="button" class="no_toc btn btn-primary" data-bs-toggle="modal" data-bs-target="#modal-<%= element_id %>-side-by-side">
         View Side-by-side
       </button>
     </li>

data/rspec-documentation/pages/001-Quickstart.md

@@ -6,12 +6,20 @@ Install _RSpec Documentation_:
 $ gem install rspec-documentation
 ```
 
+Or add to your `Gemfile`:
+
+```ruby
+gem 'rspec-documentation'
+```
+
 Initialize your project:
 
 ```console
 $ rspec-documentation
 ```
 
-A placeholder `000-Introduction.md` file with a basic example spec will be automatically generated.
+A few placeholder files with a basic example spec will be automatically generated. See the [File System](file-system.html) section for full details on the directory layout.
 
 The documentation generator will provide you with a link to your interactive documentation bundle. Open it in your browser and then start adding specs to more _Markdown_ files. When you're ready, upload the static documentation bundle to your favourite _CDN_.
+
+Whenever you add a `.md` file to your `rpsec-documentation/pages` directory, run `rspec-documentation` again to re-build your documentation bundle.

data/rspec-documentation/pages/020-Running Tests.md

@@ -16,26 +16,11 @@ Running specs...
   Total build time: 0.63 seconds, examples executed in 0.0018 seconds.
 ```
 
-Documentation will only be generated if all tests pass. A summary of failures is provided if the suite does not run successfully:
-
-```console
-$ rspec-documentation
-
-    rspec-documentation/pages/030-Examples/010-Basic.md:23
-
-    subject { 'my value' }
-
-    it { is_expected.to eql 'not my value' }
+## Options
 
+The following command-line options are supported:
 
-    expected: "not my value"
-         got: "my value"
-
-    (compared using eql?)
-
-6 examples, 1 failure.
-
-Failed examples:
-
-  rspec-documentation/pages/030-Examples/010-Basic.md:23
-```
+|Option|Variant|Description|
+|-|-|-|
+|`--fail-fast`|`-F`|Abort the run after the first failure.|
+|`--backtrace`|`-b`|Enable full backtrace.|

data/rspec-documentation/pages/030-Examples/012-Regular it Blocks.md

@@ -1,23 +1,23 @@
-## Regular `it` blocks
+# Regular `it` blocks
 
-### Markdown
+## Markdown
 
 ````markdown
 ```rspec
-subject { 'my other value' }
+subject(:value) { 'my other value' }
 
 it 'contains some expected text' do
-  expect(subject).to eql 'other value'
+  expect(subjvalue).to eql 'other value'
 end
 ```
 ````
 
-### Output
+## Output
 
 ```rspec
-subject { 'my other value' }
+subject(:value) { 'my other value' }
 
 it 'contains some expected text' do
-  expect(subject).to include 'other value'
+  expect(value).to include 'other value'
 end
 ```

data/rspec-documentation/pages/030-Examples/020-HTML.md

@@ -1,4 +1,4 @@
-## HTML
+# HTML
 
 Setting the code block language to `rspec:html` indicates that the output should be treated as _HTML_ which adds a tab displaying auto-formatted _HTML_ and another tab showing the rendered output.
 
@@ -7,16 +7,16 @@ Setting the code block language to `rspec:html` indicates that the output should
 ````markdown
 ```rspec:html
 subject do
-<<~HTML
-  <table class="table">
-    <thead>
-      <tr><th>Heading 1</th><th>Heading 2</th></tr>
-    </thead>
-    <tbody>
-      <tr><td>Value 1</td><td>Value 2</td></tr>
-      <tr><td>Value 3</td><td>Value 4</td></tr>
-    </tbody>
-  </table>
+  <<~HTML
+    <table class="table">
+      <thead>
+        <tr><th>Heading 1</th><th>Heading 2</th></tr>
+      </thead>
+      <tbody>
+        <tr><td>Value 1</td><td>Value 2</td></tr>
+        <tr><td>Value 3</td><td>Value 4</td></tr>
+      </tbody>
+    </table>
   HTML
 end
 
@@ -28,8 +28,8 @@ it { is_expected.to include 'Value 1' }
 
 ```rspec:html
 subject do
-<<~HTML
-  <table class="table">
+  <<~HTML
+    <table class="table">
     <thead>
       <tr><th>Heading 1</th><th>Heading 2</th></tr>
     </thead>
@@ -37,7 +37,7 @@ subject do
       <tr><td>Value 1</td><td>Value 2</td></tr>
       <tr><td>Value 3</td><td>Value 4</td></tr>
     </tbody>
-  </table>
+    </table>
   HTML
 end
 

data/rspec-documentation/pages/030-Examples/030-ANSI.md

@@ -24,9 +24,9 @@ it { is_expected.to include "\e[38;2;235;12;186mRGB PINK" }
 ```rspec:ansi
 subject do
   "\e[34mfoo\e[0m\e[0m \e[32mbar \e[36mfoo, bar, baz\e[0m\e[32m with " \
-  "\e[36mqux\e[0m\e[32m and quux\e[0m\e[0m and corge with " \
-  "\e[38;5;153mpale blue and " \
-  "\e[38;2;235;12;186mRGB PINK\e[0m\e[0m"
+    "\e[36mqux\e[0m\e[32m and quux\e[0m\e[0m and corge with " \
+    "\e[38;5;153mpale blue and " \
+    "\e[38;2;235;12;186mRGB PINK\e[0m\e[0m"
 end
 
 it { is_expected.to include "\e[38;2;235;12;186mRGB PINK" }

data/rspec-documentation/pages/030-Examples/040-JSON.md

@@ -6,7 +6,7 @@ If your code outputs _JSON_, use the ```` ```rspec:json ```` formatter to pretti
 
 ````markdown
 ```rspec:json
-subject do
+subject(:json) do
   {
     'key' => 'value',
     'array' => [1, 2, 3],
@@ -16,7 +16,7 @@ subject do
 end
 
 it 'has expected key/value' do
-  expect(JSON.parse(subject)).to include({ 'key' => 'value' })
+  expect(JSON.parse(json)).to include({ 'key' => 'value' })
 end
 ```
 ````
@@ -24,7 +24,7 @@ end
 ## Output
 
 ```rspec:json
-subject do
+subject(:json) do
   {
     'key' => 'value',
     'array' => [1, 2, 3],
@@ -34,6 +34,6 @@ subject do
 end
 
 it 'has expected key/value' do
-  expect(JSON.parse(subject)).to include({ 'key' => 'value' })
+  expect(JSON.parse(json)).to include({ 'key' => 'value' })
 end
 ```

data/rspec-documentation/pages/030-Examples/050-YAML.md

@@ -6,7 +6,7 @@ If your code outputs _YAML_, use the ```` ```rspec:yaml ```` formatter to pretti
 
 ````markdown
 ```rspec:yaml
-subject do
+subject(:yaml) do
   {
     'key' => 'value',
     'array' => [1, 2, 3],
@@ -16,7 +16,7 @@ subject do
 end
 
 it 'has expected key/value' do
-  expect(YAML.safe_load(subject)).to include({ 'key' => 'value' })
+  expect(YAML.safe_load(yaml)).to include({ 'key' => 'value' })
 end
 ```
 ````
@@ -24,7 +24,7 @@ end
 ## Output
 
 ```rspec:yaml
-subject do
+subject(:yaml) do
   {
     'key' => 'value',
     'array' => [1, 2, 3],
@@ -34,6 +34,6 @@ subject do
 end
 
 it 'has expected key/value' do
-  expect(YAML.safe_load(subject)).to include({ 'key' => 'value' })
+  expect(YAML.safe_load(yaml)).to include({ 'key' => 'value' })
 end
 ```

data/rspec-documentation/pages/030-Examples/060-XML.md

@@ -6,10 +6,10 @@ If your code outputs _XML_, use the ```` ```rspec:xml ```` formatter to prettify
 
 ````markdown
 ```rspec:xml
-subject { '<?xml version="1.0" encoding="UTF-8"?><foo><bar>baz</bar></foo>' }
+subject(:xml) { '<?xml version="1.0" encoding="UTF-8"?><foo><bar>baz</bar></foo>' }
 
 it 'has expected key/value' do
-  expect(Nokogiri::XML.parse(subject).xpath('//foo/bar').text).to eql 'baz'
+  expect(Nokogiri::XML.parse(xml).xpath('//foo/bar').text).to eql 'baz'
 end
 ```
 ````
@@ -17,9 +17,9 @@ end
 ## Output
 
 ```rspec:xml
-subject { '<?xml version="1.0" encoding="UTF-8"?><foo><bar>baz</bar></foo>' }
+subject(:xml) { '<?xml version="1.0" encoding="UTF-8"?><foo><bar>baz</bar></foo>' }
 
 it 'has expected key/value' do
-  expect(Nokogiri::XML.parse(subject).xpath('//foo/bar').text).to eql 'baz'
+  expect(Nokogiri::XML.parse(xml).xpath('//foo/bar').text).to eql 'baz'
 end
 ```

data/rspec-documentation/pages/060-Configuration/Index Search.md

@@ -0,0 +1,13 @@
+# Index Search
+
+The index above the navigation tree is enabled by default.
+
+To disable the index search, set `config.index_search = false`:
+
+```ruby
+# rspec-documentation/spec_helper.rb
+
+RSpec::Documentation.configure do |config|
+  config.index_search = false
+end
+```

data/rspec-documentation/pages/060-Configuration/Table of Contents.md

@@ -0,0 +1,35 @@
+# Table of Contents
+
+A table of contents for each page is generated by default. The items in the table of contents are derived from the headers in each section (i.e. _Markdown_ elements defined with one or more `#` characters).
+
+To disable the table of contents, set `config.table_of_contents` to `false`:
+
+```ruby
+# spec/spec_helper.rb
+
+RSpec::Documentation.configure do |config|
+  config.table_of_contents = false # Default: true
+end
+```
+
+## Overriding for Specific Pages
+
+If you want to disable the Table of Contents globally but enable for specific pages, add the following anywhere in your _Markdown_ document:
+
+```markdown
+* TOC
+{:toc}
+```
+
+## Omit a Specific Header from Table of Contents
+
+To omit a specific header element from the Table of Contents, add `{:.no_toc}` underneath the header:
+
+```markdown
+## Header included in Table of Contents
+
+## Header not included in Table of Contents
+{:.no_toc}
+```
+
+See the [`kramdown` documentation](https://kramdown.gettalong.org/converter/html.html#toc) for more details. Aside from injecting _RSpec_ examples into the output, each _Markdown_ document is passed transparently to _kramdown_ for processing.

data/rspec-documentation/pages/080-Rubocop.md

@@ -0,0 +1,36 @@
+# RuboCop
+
+An extension gem for [RuboCop](https://rubocop.org) is available. The extension allows _RuboCop_ to extract all examples from your documentation pages and identify any failures. With the extension enabled, a `rubocop` run will include all of the examples in your documentation seamlessly.
+
+It is highly recommended to use the official [`rubocop-rspec`](https://github.com/rubocop/rubocop-rspec) extension in conjunction with _RSpec::Documentation_.
+
+## Installation
+
+Add the following to your `Gemfile`:
+
+```ruby
+gem 'rubocop-rspec-documentation', require: false
+```
+
+## Configuration
+
+Add the following configuration to your `.rubocop.yml` to enable the extension:
+
+```yaml
+# .rubocop.yml
+
+require:
+- rubocop-rspec-documentation
+```
+
+_RuboCop_ will now look for files in `rspec-documentation/pages/**/*.md` and the provided extension will do the required parsing/extracting/offsetting, allowing _RuboCop_ to work as normal.
+
+The following cops are disabled for your documentation examples as they cannot be sensibly addressed within each example:
+
+* `Naming/FileName`
+* `Gemspec/RequiredRubyVersion`
+* `Style/FrozenStringLiteralComment`
+
+## Autocorrect
+
+There is currently an issue using auto-correct with _RuboCop_, causing infinite loops with indentation corrections. Possibly a bug in _RuboCop's_ extension mechanism - avoid using auto-correct with your _Markdown_ files until this has been resolved.

data/rspec-documentation/spec_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'devpack'
 require 'nokogiri'
 
 RSpec::Documentation.configure do |config|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-documentation
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Bob Farrell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-06-11 00:00:00.000000000 Z
+date: 2023-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: htmlbeautifier
@@ -177,9 +177,11 @@ files:
 - lib/templates/layout.css.erb
 - lib/templates/layout.html.erb
 - lib/templates/layout.js.erb
+- lib/templates/link.svg.erb
 - lib/templates/modal_spec.html.erb
 - lib/templates/moon.svg.erb
 - lib/templates/script_tags.html.erb
+- lib/templates/spec_helper.rb.erb
 - lib/templates/stylesheet_links.html.erb
 - lib/templates/sun.svg.erb
 - lib/templates/tabbed_spec.html.erb
@@ -229,12 +231,15 @@ files:
 - rspec-documentation/pages/040-Spec Helper.md
 - rspec-documentation/pages/050-Linking.md
 - rspec-documentation/pages/060-Configuration.md
-- rspec-documentation/pages/060-Configuration/010-Context.md
-- rspec-documentation/pages/060-Configuration/020-Build Paths.md
-- rspec-documentation/pages/060-Configuration/030-Attribution.md
-- rspec-documentation/pages/060-Configuration/040-Hooks.md
-- rspec-documentation/pages/060-Configuration/050-Consistent Height.md
+- rspec-documentation/pages/060-Configuration/Attribution.md
+- rspec-documentation/pages/060-Configuration/Build Paths.md
+- rspec-documentation/pages/060-Configuration/Consistent Height.md
+- rspec-documentation/pages/060-Configuration/Context.md
+- rspec-documentation/pages/060-Configuration/Hooks.md
+- rspec-documentation/pages/060-Configuration/Index Search.md
+- rspec-documentation/pages/060-Configuration/Table of Contents.md
 - rspec-documentation/pages/070-Publishing.md
+- rspec-documentation/pages/080-Rubocop.md
 - rspec-documentation/pages/500-License.md
 - rspec-documentation/spec_helper.rb
 - sig/rspec/documentation.rbs