rspec-documentation 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 283bdf52a7ed9f190175ab2d12dc9e1d206a90b0cfdb439713e506921efb2853
-  data.tar.gz: acab855a9d1ce848cf6d11fd5662a99b61d7ac1349ac49edb46519c59e327463
+  metadata.gz: 6eb4258635900a3617ddf6ab4cdfb7fe1d1cba62fbd8231f11437cf9b9734c6b
+  data.tar.gz: f5db6165cfd08d759765d4e50a0398bfdb0ab99dee84567fd535bd97cd30f0a4
 SHA512:
-  metadata.gz: ca29bcf6ad430a865f329586db18807a8d5b2f07f545051b803ed936d4c4bf606d2b1cc554b09db575cc813b48ba6538aac000a01b047a2a76d75daafe7444f2
-  data.tar.gz: 38d5455b372da3ea5798acdd10e28c86bfec33bc4ab697417122edc3a0d7912d257b16af3c245601fdba7a20c2aad185ec15160ee2fb9b821dd6e938a6a94ce5
+  metadata.gz: e25685a33fb2cc2bace75aa20c72f2b33407f2edec5a14840163cced2662fd852d3c87f8e4b31741b15825311365348f22cf5754b1850ddec1196bba64181a02
+  data.tar.gz: 3678422ca81bc09c5cd68db061b6a81746d21fb848824e229369721e727ac01f4fa4e517263ef9d47b8f1457f336d7dd6a0fdea0ee6ed63e498d62995f7c4102

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-documentation (0.0.4)
+    rspec-documentation (0.0.6)
       htmlbeautifier (~> 1.4)
       kramdown (~> 2.4)
       kramdown-parser-gfm (~> 1.1)

data/README.md

@@ -24,4 +24,6 @@ it { is_expected.to eql 'my subject' }
 ```
 ````
 
+## Documentation
+
 View the [full documentation](https://docs.bob.frl/rspec-documentation) (built using Rspec Documentation!) for detailed usage instructions.

data/lib/rspec/documentation/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Documentation
-    VERSION = '0.0.5'
+    VERSION = '0.0.6'
   end
 end

data/lib/rspec_documentation/configuration.rb

@@ -3,8 +3,11 @@
 module RSpecDocumentation
   # Configures the rspec-documentation gem, allows setting a context that makes values available to each example.
   class Configuration
+    attr_reader :hooks
+
     def initialize
       @context_defined = false
+      @hooks = {}
     end
 
     def context_defined?
@@ -24,5 +27,9 @@ module RSpecDocumentation
       @context_defined = true
       ::RSpec.shared_context('__rspec_documentation', &block)
     end
+
+    def hook(name, &block)
+      hooks[name] = block
+    end
   end
 end

data/lib/rspec_documentation/kramdown_html_converter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Kramdown
+  module Converter
+    # Custom HTML converter for kramdown. Invoked with `Kramdown::Document#to_html_rspec_documentation`.
+    # Applies a custom CSS class to Markdown tables when rendered to HTML.
+    class HtmlRspecDocumentation < Converter::Html
+      def convert_table(element, indent)
+        element.attr['class'] ||= 'rspec-documentation-table table'
+        super
+      end
+    end
+  end
+end

data/lib/rspec_documentation/parsed_document.rb

@@ -12,7 +12,7 @@ module RSpecDocumentation
     end
 
     def html
-      document.to_html
+      document.to_html_rspec_documentation
     end
 
     def execute_and_substitute_examples!

data/lib/rspec_documentation/rspec/failure.rb

@@ -14,7 +14,7 @@ module RSpecDocumentation
       end
 
       def message
-        "\n#{formatted_header}\n\n#{formatted_source}\n\n#{formatted_cause}\n\n"
+        "\n#{formatted_header}\n\n#{formatted_source}\n\n#{formatted_cause}\n\n#{formatted_backtrace}\n\n"
       end
 
       private
@@ -37,6 +37,13 @@ module RSpecDocumentation
         paintbrush { red indented(without_anonymous_group_text(cause.message)) }
       end
 
+      def formatted_backtrace
+        cause.backtrace
+             .take_while { |line| line.start_with?(Dir.pwd) }
+             .map { |line| paintbrush { red "    #{line.sub("#{Dir.pwd}/", '')}" } }
+             .join("\n")
+      end
+
       def indented(text)
         text.split("\n").map { |line| "    #{line}" }.join("\n")
       end

data/lib/rspec_documentation/spec.rb

@@ -71,7 +71,7 @@ module RSpecDocumentation
     def example_group
       # rubocop:disable Style/DocumentDynamicEvalDefinition, Security/Eval
       @example_group ||= binding.eval(
-        <<-SPEC, __FILE__, __LINE__.to_i
+        <<-SPEC, path.to_s, location
           ::RSpec::Core::ExampleGroup.describe do
             after { RSpecDocumentation::Spec.subjects << subject if RSpecDocumentation::Spec.subjects.empty? }
             include_context '__rspec_documentation' do

data/lib/rspec_documentation.rb

@@ -37,12 +37,15 @@ require_relative 'rspec_documentation/documentation'
 require_relative 'rspec_documentation/page_collection'
 require_relative 'rspec_documentation/page_tree'
 require_relative 'rspec_documentation/page_tree_element'
+require_relative 'rspec_documentation/kramdown_html_converter'
 
 # Internal module used by RSpec::Documentation to run examples and write output into an HTML document.
 module RSpecDocumentation
   class Error < StandardError; end
   class MissingFileError < Error; end
 
+  @hooks = {}
+
   def self.root
     Pathname.new(File.dirname(__dir__))
   end
@@ -58,6 +61,10 @@ module RSpecDocumentation
     ERB.new(root.join('lib/templates/themes', "#{name}.css").read).result(binding)
   end
 
+  def self.hook(name)
+    configuration.hooks.fetch(name, nil)&.call
+  end
+
   def self.context
     yield configuration.context if block_given?
     configuration.context

data/lib/templates/layout.css.erb

@@ -45,6 +45,15 @@ body {
   background-color: #fff;
 }
 
+table.rspec-documentation-table td, table.rspec-documentation-table th {
+  border: 1px solid #cdcdcd;
+  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;
+}
+
 [data-bs-theme="dark"] .header-wrapper {
   background-color: #212121;
 }

data/lib/templates/layout.html.erb

@@ -2,6 +2,7 @@
   <head>
     <meta charset="utf-8" />
     <%= RSpecDocumentation.template(:stylesheet_links).result(binding) %>
+    <%= RSpecDocumentation.hook(:after_head) %>
   </head>
 
   <body>
@@ -10,6 +11,8 @@
         <%= header %>
       </div>
 
+      <%= RSpecDocumentation.hook(:after_header) %>
+
       <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">
@@ -19,9 +22,13 @@
           </ol>
         </div>
 
+        <%= RSpecDocumentation.hook(:before_content) %>
+
         <div class="col content" style="max-width: 80%">
           <%= html %>
+          <%= RSpecDocumentation.hook(:after_content) %>
           <%= footer %>
+          <%= RSpecDocumentation.hook(:after_footer) %>
         </div>
       </div>
     </div>

data/lib/templates/modal_spec.html.erb

@@ -33,7 +33,7 @@
                 <h5>Rendered Output</h5>
               <% end %>
               <hr/>
-              <div class="p-3 mb-5 <%= render_raw? ? nil : 'code highlight' %>">
+              <div class="p-3 mb-5 border <%= render_raw? ? nil : 'code highlight' %>">
                 <%= rendered_output %>
               </div>
             </div>

data/lib/templates/tabbed_spec.html.erb

@@ -73,7 +73,7 @@
          id="rendered-<%= element_id %>"
          role="tabpanel"
          aria-labelledby="rendered-<%= element_id %>-tab">
-      <div class="p-3 mb-5 mt-3 <%= render_raw? ? nil : 'code highlight' %>">
+      <div class="p-3 mb-5 border mt-3 <%= render_raw? ? nil : 'code highlight' %>">
         <%= rendered_output %>
       </div>
     </div>

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

@@ -4,10 +4,10 @@
 
 ````markdown
 ```rspec
-subject { 'my value' }
+subject { 'my other value' }
 
 it 'contains some expected text' do
-  expect(subject).to eql 'my value'
+  expect(subject).to eql 'other value'
 end
 ```
 ````

data/rspec-documentation/pages/060-Configuration/020-Build Paths.md

@@ -15,7 +15,7 @@ $ RSPEC_DOCUMENTATION_BUNDLE_PATH=/tmp/my-documentation-bundle/ rspec-documentat
 
   Created 13 pages.
 
-  View your documentation here: /tmp/my-documentation-bundle/introduction.html
+  View your documentation here: /tmp/my-documentation-bundle/index.html
 ```
 
 ## `RSPEC_DOCUMENTATION_URL_ROOT`
@@ -29,5 +29,5 @@ $ RSPEC_DOCUMENTATION_URL_ROOT=/rspec-documentation rspec-documentation
 
   Created 13 pages.
 
-  View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/introduction.html
+  View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/index.html
 ```

data/rspec-documentation/pages/060-Configuration/040-Hooks.md

@@ -0,0 +1,31 @@
+# Hooks
+
+_RSpec::Documentation_ provides hooks for inserting content into various places rendered _HTML_ documents for each page of your documentation.
+
+To configure hooks, add the following to `rspec-documentation/spec_helper.rb`:
+
+```ruby
+RSpec::Documentation.configure do |config|
+  config.hook(:after_head) { '<style>h1 { font-size: 10rem; }</style>' }
+end
+```
+
+In practice you will most likely load content from a file using `File.read` or similar. You are free to store supplementary content anywhere in your project, e.g. you may want to create `rspec-documentation/assets` and create a hook such as:
+
+```ruby
+RSpec::Documentation.configure do |config|
+  config.hook(:after_head) do
+    "<script>#{File.read('rspec-documentation/assets/fontawesome.js')}</script>"
+  end
+end
+```
+
+## Available Hooks
+
+| Hook | Description |
+|-|-|
+| `after_head` | Inserts content immediately before the closing `</head>` tag, after the default head content. Use this to override any styling or add `<script>` and `<link>` tags. |
+| `after_header` | Inserts content immediately after the main document header. Use this to insert custom content underneath the header for each page. |
+| `before_content` | Inserts content immediately before the main document content, between the navigation tree and each rendered documentation page. |
+| `after_content` | Inserts content immediately after the main documentation content, before the footer. |
+| `after_footer` | Inserts content immediately below the footer. |

data/rspec-documentation/pages/070-Publishing.md

@@ -8,6 +8,6 @@ $ RSPEC_DOCUMENTATION_URL_ROOT='/rspec-documentation' rspec-documentation
 $ rsync --delete -r rspec-documentation/bundle/ docs01.bob.frl:/mnt/docs/rspec-documentation/
 ```
 
-This command was used to publish this documentation to an _AWS EC2_ instance which is serving the content that you are reading now. You are welcome to view the [Terraform code](https://github.com/bobf/docs.bob.frl-terraform) that manages this infrastructure.
+This command was used to publish the documentation you are currently reading to an _AWS EC2_ instance which is serving the content that you are reading now. You are welcome to view the [Terraform code](https://github.com/bobf/docs.bob.frl-terraform) that manages this infrastructure.
 
-You can use any web host you like to serve this documentation since the build output is exclusively static _HTML_ plus a _Javascript_ and _CSS_ bundle. [Surge](https://surge.sh) is a good place to start if you are looking for a simple _CDN_ to get started with.
+You can use any web host you like to serve this documentation since the build output is exclusively static _HTML_ plus a self-contained _Javascript_ and _CSS_ bundle. [Surge](https://surge.sh) is a good place to start if you are looking for a simple _CDN_ to get started with.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-documentation
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Bob Farrell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-06-05 00:00:00.000000000 Z
+date: 2023-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: htmlbeautifier
@@ -154,6 +154,7 @@ files:
 - lib/rspec_documentation/formatters/yaml.rb
 - lib/rspec_documentation/html_element.rb
 - lib/rspec_documentation/javascript_bundle.rb
+- lib/rspec_documentation/kramdown_html_converter.rb
 - lib/rspec_documentation/markdown_renderer.rb
 - lib/rspec_documentation/page_collection.rb
 - lib/rspec_documentation/page_tree.rb
@@ -231,6 +232,7 @@ files:
 - 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/070-Publishing.md
 - rspec-documentation/pages/500-License.md
 - rspec-documentation/spec_helper.rb