rspec-documentation 0.0.5 → 0.0.7

Sign up to get free protection for your applications and to get access to all the features.
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