rspec-documentation 0.0.5 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. checksums.yaml +4 -4
  2. data/Gemfile.lock +1 -1
  3. data/README.md +3 -1
  4. data/lib/rspec/documentation/version.rb +1 -1
  5. data/lib/rspec_documentation/configuration.rb +10 -0
  6. data/lib/rspec_documentation/formatters/html.rb +3 -1
  7. data/lib/rspec_documentation/kramdown_html_converter.rb +14 -0
  8. data/lib/rspec_documentation/parsed_document.rb +2 -2
  9. data/lib/rspec_documentation/rspec/failure.rb +8 -1
  10. data/lib/rspec_documentation/spec.rb +1 -1
  11. data/lib/rspec_documentation.rb +7 -0
  12. data/lib/templates/layout.css.erb +12 -1
  13. data/lib/templates/layout.html.erb +7 -0
  14. data/lib/templates/modal_spec.html.erb +1 -1
  15. data/lib/templates/tabbed_spec.html.erb +1 -1
  16. data/rspec-documentation/pages/030-Examples/012-Regular it Blocks.md +2 -2
  17. data/rspec-documentation/pages/060-Configuration/020-Build Paths.md +2 -2
  18. data/rspec-documentation/pages/060-Configuration/040-Hooks.md +31 -0
  19. data/rspec-documentation/pages/060-Configuration/050-Consistent Height.md +16 -0
  20. data/rspec-documentation/pages/070-Publishing.md +2 -2
  21. metadata +5 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 283bdf52a7ed9f190175ab2d12dc9e1d206a90b0cfdb439713e506921efb2853
4
- data.tar.gz: acab855a9d1ce848cf6d11fd5662a99b61d7ac1349ac49edb46519c59e327463
3
+ metadata.gz: da04d0bb8e452ebcf2858bff1c50b704099bd28ef683e4bd18759952195b8543
4
+ data.tar.gz: db7bb967b2c35fd6b972f3ff295561e1731ade67d07c9d6132f797504d855cc3
5
5
  SHA512:
6
- metadata.gz: ca29bcf6ad430a865f329586db18807a8d5b2f07f545051b803ed936d4c4bf606d2b1cc554b09db575cc813b48ba6538aac000a01b047a2a76d75daafe7444f2
7
- data.tar.gz: 38d5455b372da3ea5798acdd10e28c86bfec33bc4ab697417122edc3a0d7912d257b16af3c245601fdba7a20c2aad185ec15160ee2fb9b821dd6e938a6a94ce5
6
+ metadata.gz: 733742f420606fab2d6cb27ab9c180e2c30260184e903314337ae994453de0d3863e00df34407f613103d9bef55697fea044fde7e436018e50fdf39a68f41e02
7
+ data.tar.gz: 4271936018c835d3e6af24d8a1f5329a3b229b89528d53e04cba2a44e42b459f49a4fde648820a9e1e9a0710fe692db891ecc866d5a5a9767f7ad9098c30f330
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- rspec-documentation (0.0.4)
4
+ rspec-documentation (0.0.7)
5
5
  htmlbeautifier (~> 1.4)
6
6
  kramdown (~> 2.4)
7
7
  kramdown-parser-gfm (~> 1.1)
data/README.md CHANGED
@@ -13,7 +13,7 @@ There is no _DSL_ to learn and vanilla _RSpec_ examples are used to generate inp
13
13
 
14
14
  The following is an example _Markdown_ file.
15
15
 
16
- ````console
16
+ ````markdown
17
17
  # An example test
18
18
 
19
19
  This is a very simple test:
@@ -24,4 +24,6 @@ it { is_expected.to eql 'my subject' }
24
24
  ```
25
25
  ````
26
26
 
27
+ ## Documentation
28
+
27
29
  View the [full documentation](https://docs.bob.frl/rspec-documentation) (built using Rspec Documentation!) for detailed usage instructions.
data/lib/rspec/documentation/version.rb CHANGED
@@ -2,6 +2,6 @@
2
2
 
3
3
  module RSpec
4
4
  module Documentation
5
- VERSION = '0.0.5'
5
+ VERSION = '0.0.7'
6
6
  end
7
7
  end
data/lib/rspec_documentation/configuration.rb CHANGED
@@ -3,8 +3,14 @@
3
3
  module RSpecDocumentation
4
4
  # Configures the rspec-documentation gem, allows setting a context that makes values available to each example.
5
5
  class Configuration
6
+ attr_reader :hooks
7
+ attr_accessor :consistent_height, :max_height
8
+
6
9
  def initialize
7
10
  @context_defined = false
11
+ @consistent_height = false
12
+ @max_height = '30rem'
13
+ @hooks = {}
8
14
  end
9
15
 
10
16
  def context_defined?
@@ -24,5 +30,9 @@ module RSpecDocumentation
24
30
  @context_defined = true
25
31
  ::RSpec.shared_context('__rspec_documentation', &block)
26
32
  end
33
+
34
+ def hook(name, &block)
35
+ hooks[name] = block
36
+ end
27
37
  end
28
38
  end
data/lib/rspec_documentation/formatters/html.rb CHANGED
@@ -5,6 +5,8 @@ module RSpecDocumentation
5
5
  # Beautifies HTML received from a `subject`, renders the raw subject to be inserted directly
6
6
  # into the output document.
7
7
  class Html
8
+ DOCTYPE_TAG = '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" ' \
9
+ '"http://www.w3.org/TR/REC-html40/loose.dtd">'
8
10
  def initialize(subject:)
9
11
  @subject = subject
10
12
  end
@@ -16,7 +18,7 @@ module RSpecDocumentation
16
18
  end
17
19
 
18
20
  def rendered_output
19
- subject
21
+ subject&.to_s&.sub(DOCTYPE_TAG, '')
20
22
  end
21
23
 
22
24
  def render_raw?
data/lib/rspec_documentation/kramdown_html_converter.rb ADDED
@@ -0,0 +1,14 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Kramdown
4
+ module Converter
5
+ # Custom HTML converter for kramdown. Invoked with `Kramdown::Document#to_html_rspec_documentation`.
6
+ # Applies a custom CSS class to Markdown tables when rendered to HTML.
7
+ class HtmlRspecDocumentation < Converter::Html
8
+ def convert_table(element, indent)
9
+ element.attr['class'] ||= 'rspec-documentation-table table'
10
+ super
11
+ end
12
+ end
13
+ end
14
+ end
data/lib/rspec_documentation/parsed_document.rb CHANGED
@@ -12,13 +12,13 @@ module RSpecDocumentation
12
12
  end
13
13
 
14
14
  def html
15
- document.to_html
15
+ document.to_html_rspec_documentation
16
16
  end
17
17
 
18
18
  def execute_and_substitute_examples!
19
19
  specs.each do |spec|
20
20
  spec.run
21
- break failures << spec.failure unless spec.failure.nil?
21
+ next failures << spec.failure unless spec.failure.nil?
22
22
 
23
23
  spec.parent.children[spec.index] = spec_element(spec)
24
24
  end
data/lib/rspec_documentation/rspec/failure.rb CHANGED
@@ -14,7 +14,7 @@ module RSpecDocumentation
14
14
  end
15
15
 
16
16
  def message
17
- "\n#{formatted_header}\n\n#{formatted_source}\n\n#{formatted_cause}\n\n"
17
+ "\n#{formatted_header}\n\n#{formatted_source}\n\n#{formatted_cause}\n\n#{formatted_backtrace}\n\n"
18
18
  end
19
19
 
20
20
  private
@@ -37,6 +37,13 @@ module RSpecDocumentation
37
37
  paintbrush { red indented(without_anonymous_group_text(cause.message)) }
38
38
  end
39
39
 
40
+ def formatted_backtrace
41
+ cause.backtrace
42
+ &.take_while { |line| line.start_with?(Dir.pwd) }
43
+ &.map { |line| paintbrush { red " #{line.sub("#{Dir.pwd}/", '')}" } }
44
+ &.join("\n")
45
+ end
46
+
40
47
  def indented(text)
41
48
  text.split("\n").map { |line| " #{line}" }.join("\n")
42
49
  end
data/lib/rspec_documentation/spec.rb CHANGED
@@ -71,7 +71,7 @@ module RSpecDocumentation
71
71
  def example_group
72
72
  # rubocop:disable Style/DocumentDynamicEvalDefinition, Security/Eval
73
73
  @example_group ||= binding.eval(
74
- <<-SPEC, __FILE__, __LINE__.to_i
74
+ <<-SPEC, path.to_s, location
75
75
  ::RSpec::Core::ExampleGroup.describe do
76
76
  after { RSpecDocumentation::Spec.subjects << subject if RSpecDocumentation::Spec.subjects.empty? }
77
77
  include_context '__rspec_documentation' do
data/lib/rspec_documentation.rb CHANGED
@@ -37,12 +37,15 @@ require_relative 'rspec_documentation/documentation'
37
37
  require_relative 'rspec_documentation/page_collection'
38
38
  require_relative 'rspec_documentation/page_tree'
39
39
  require_relative 'rspec_documentation/page_tree_element'
40
+ require_relative 'rspec_documentation/kramdown_html_converter'
40
41
 
41
42
  # Internal module used by RSpec::Documentation to run examples and write output into an HTML document.
42
43
  module RSpecDocumentation
43
44
  class Error < StandardError; end
44
45
  class MissingFileError < Error; end
45
46
 
47
+ @hooks = {}
48
+
46
49
  def self.root
47
50
  Pathname.new(File.dirname(__dir__))
48
51
  end
@@ -58,6 +61,10 @@ module RSpecDocumentation
58
61
  ERB.new(root.join('lib/templates/themes', "#{name}.css").read).result(binding)
59
62
  end
60
63
 
64
+ def self.hook(name)
65
+ configuration.hooks.fetch(name, nil)&.call
66
+ end
67
+
61
68
  def self.context
62
69
  yield configuration.context if block_given?
63
70
  configuration.context
data/lib/templates/layout.css.erb CHANGED
@@ -7,6 +7,7 @@
7
7
  MonokaiSublime, Pastie, ThankfulEyes, Tulip */
8
8
  <%= Rouge::Theme.find('molokai').render(scope: '.highlight') %>
9
9
 
10
+ <% if RSpecDocumentation.configuration.consistent_height %>
10
11
  /* https://stackoverflow.com/a/61587938 */
11
12
  .consistent-height .tab-content {
12
13
  display: flex;
@@ -22,6 +23,7 @@
22
23
  .consistent-height .tab-content > .active {
23
24
  visibility: visible;
24
25
  }
26
+ <% end %>
25
27
 
26
28
  @keyframes fade-in {
27
29
  from {
@@ -45,6 +47,15 @@ body {
45
47
  background-color: #fff;
46
48
  }
47
49
 
50
+ table.rspec-documentation-table td, table.rspec-documentation-table th {
51
+ border: 1px solid #cdcdcd;
52
+ padding: 0.5rem 1rem;
53
+ }
54
+
55
+ [data-bs-theme="dark"] table.rspec-documentation-table td, [data-bs-theme="dark"] table.rspec-documentation-table th {
56
+ border: 1px solid #4e4e4e;
57
+ }
58
+
48
59
  [data-bs-theme="dark"] .header-wrapper {
49
60
  background-color: #212121;
50
61
  }
@@ -79,7 +90,7 @@ h1.title a {
79
90
 
80
91
  .code {
81
92
  font-family: monospace;
82
- max-height: 30rem;
93
+ max-height: <%= RSpecDocumentation.configuration.max_height %>;
83
94
  overflow-y: auto;
84
95
  }
85
96
 
data/lib/templates/layout.html.erb CHANGED
@@ -2,6 +2,7 @@
2
2
  <head>
3
3
  <meta charset="utf-8" />
4
4
  <%= RSpecDocumentation.template(:stylesheet_links).result(binding) %>
5
+ <%= RSpecDocumentation.hook(:after_head) %>
5
6
  </head>
6
7
 
7
8
  <body>
@@ -10,6 +11,8 @@
10
11
  <%= header %>
11
12
  </div>
12
13
 
14
+ <%= RSpecDocumentation.hook(:after_header) %>
15
+
13
16
  <div class="row flex-nowrap">
14
17
  <div class="col-sm-2 fs-6 mt-1 ms-3 me-3">
15
18
  <ol class="page-tree hidden position-fixed">
@@ -19,9 +22,13 @@
19
22
  </ol>
20
23
  </div>
21
24
 
25
+ <%= RSpecDocumentation.hook(:before_content) %>
26
+
22
27
  <div class="col content" style="max-width: 80%">
23
28
  <%= html %>
29
+ <%= RSpecDocumentation.hook(:after_content) %>
24
30
  <%= footer %>
31
+ <%= RSpecDocumentation.hook(:after_footer) %>
25
32
  </div>
26
33
  </div>
27
34
  </div>
data/lib/templates/modal_spec.html.erb CHANGED
@@ -33,7 +33,7 @@
33
33
  <h5>Rendered Output</h5>
34
34
  <% end %>
35
35
  <hr/>
36
- <div class="p-3 mb-5 <%= render_raw? ? nil : 'code highlight' %>">
36
+ <div class="p-3 mb-5 border <%= render_raw? ? nil : 'code highlight' %>">
37
37
  <%= rendered_output %>
38
38
  </div>
39
39
  </div>
data/lib/templates/tabbed_spec.html.erb CHANGED
@@ -73,7 +73,7 @@
73
73
  id="rendered-<%= element_id %>"
74
74
  role="tabpanel"
75
75
  aria-labelledby="rendered-<%= element_id %>-tab">
76
- <div class="p-3 mb-5 mt-3 <%= render_raw? ? nil : 'code highlight' %>">
76
+ <div class="p-3 mb-5 border mt-3 <%= render_raw? ? nil : 'code highlight' %>">
77
77
  <%= rendered_output %>
78
78
  </div>
79
79
  </div>
data/rspec-documentation/pages/030-Examples/012-Regular it Blocks.md CHANGED
@@ -4,10 +4,10 @@
4
4
 
5
5
  ````markdown
6
6
  ```rspec
7
- subject { 'my value' }
7
+ subject { 'my other value' }
8
8
 
9
9
  it 'contains some expected text' do
10
- expect(subject).to eql 'my value'
10
+ expect(subject).to eql 'other value'
11
11
  end
12
12
  ```
13
13
  ````
data/rspec-documentation/pages/060-Configuration/020-Build Paths.md CHANGED
@@ -15,7 +15,7 @@ $ RSPEC_DOCUMENTATION_BUNDLE_PATH=/tmp/my-documentation-bundle/ rspec-documentat
15
15
 
16
16
  Created 13 pages.
17
17
 
18
- View your documentation here: /tmp/my-documentation-bundle/introduction.html
18
+ View your documentation here: /tmp/my-documentation-bundle/index.html
19
19
  ```
20
20
 
21
21
  ## `RSPEC_DOCUMENTATION_URL_ROOT`
@@ -29,5 +29,5 @@ $ RSPEC_DOCUMENTATION_URL_ROOT=/rspec-documentation rspec-documentation
29
29
 
30
30
  Created 13 pages.
31
31
 
32
- View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/introduction.html
32
+ View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/index.html
33
33
  ```
data/rspec-documentation/pages/060-Configuration/040-Hooks.md ADDED
@@ -0,0 +1,31 @@
1
+ # Hooks
2
+
3
+ _RSpec::Documentation_ provides hooks for inserting content into various places rendered _HTML_ documents for each page of your documentation.
4
+
5
+ To configure hooks, add the following to `rspec-documentation/spec_helper.rb`:
6
+
7
+ ```ruby
8
+ RSpec::Documentation.configure do |config|
9
+ config.hook(:after_head) { '<style>h1 { font-size: 10rem; }</style>' }
10
+ end
11
+ ```
12
+
13
+ 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:
14
+
15
+ ```ruby
16
+ RSpec::Documentation.configure do |config|
17
+ config.hook(:after_head) do
18
+ "<script>#{File.read('rspec-documentation/assets/fontawesome.js')}</script>"
19
+ end
20
+ end
21
+ ```
22
+
23
+ ## Available Hooks
24
+
25
+ | Hook | Description |
26
+ |-|-|
27
+ | `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. |
28
+ | `after_header` | Inserts content immediately after the main document header. Use this to insert custom content underneath the header for each page. |
29
+ | `before_content` | Inserts content immediately before the main document content, between the navigation tree and each rendered documentation page. |
30
+ | `after_content` | Inserts content immediately after the main documentation content, before the footer. |
31
+ | `after_footer` | Inserts content immediately below the footer. |
data/rspec-documentation/pages/060-Configuration/050-Consistent Height.md ADDED
@@ -0,0 +1,16 @@
1
+ # Consistent Height
2
+
3
+ Depending on your preferences, you may want to force a consistent height for tab content in each rendered example. To configure this option, set `config.consistent_height` to `true` or `false`. The default is `false`.
4
+
5
+ Setting a consistent height on output prevents content from jumping when each tab is opened but it can also result in quite large gaps beneath examples.
6
+
7
+ The max height for each example can also be configured by setting `config.max_height`, with the default being `30rem`.
8
+
9
+ ```ruby
10
+ # rspec-documentation/spec_helper.rb
11
+
12
+ RSpec::Documentation.conifgure do |config|
13
+ config.consistent_height = true # Default: false
14
+ config.max_height = '20rem' # Default: 30rem
15
+ end
16
+ ```
data/rspec-documentation/pages/070-Publishing.md CHANGED
@@ -8,6 +8,6 @@ $ RSPEC_DOCUMENTATION_URL_ROOT='/rspec-documentation' rspec-documentation
8
8
  $ rsync --delete -r rspec-documentation/bundle/ docs01.bob.frl:/mnt/docs/rspec-documentation/
9
9
  ```
10
10
 
11
- 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.
11
+ 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.
12
12
 
13
- 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.
13
+ 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 CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rspec-documentation
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.5
4
+ version: 0.0.7
5
5
  platform: ruby
6
6
  authors:
7
7
  - Bob Farrell
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2023-06-05 00:00:00.000000000 Z
11
+ date: 2023-06-11 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: htmlbeautifier
@@ -154,6 +154,7 @@ files:
154
154
  - lib/rspec_documentation/formatters/yaml.rb
155
155
  - lib/rspec_documentation/html_element.rb
156
156
  - lib/rspec_documentation/javascript_bundle.rb
157
+ - lib/rspec_documentation/kramdown_html_converter.rb
157
158
  - lib/rspec_documentation/markdown_renderer.rb
158
159
  - lib/rspec_documentation/page_collection.rb
159
160
  - lib/rspec_documentation/page_tree.rb
@@ -231,6 +232,8 @@ files:
231
232
  - rspec-documentation/pages/060-Configuration/010-Context.md
232
233
  - rspec-documentation/pages/060-Configuration/020-Build Paths.md
233
234
  - rspec-documentation/pages/060-Configuration/030-Attribution.md
235
+ - rspec-documentation/pages/060-Configuration/040-Hooks.md
236
+ - rspec-documentation/pages/060-Configuration/050-Consistent Height.md
234
237
  - rspec-documentation/pages/070-Publishing.md
235
238
  - rspec-documentation/pages/500-License.md
236
239
  - rspec-documentation/spec_helper.rb