rspec-documentation 0.0.5 → 0.0.6
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.
- checksums.yaml +4 -4
- data/Gemfile.lock +1 -1
- data/README.md +2 -0
- data/lib/rspec/documentation/version.rb +1 -1
- data/lib/rspec_documentation/configuration.rb +7 -0
- data/lib/rspec_documentation/kramdown_html_converter.rb +14 -0
- data/lib/rspec_documentation/parsed_document.rb +1 -1
- data/lib/rspec_documentation/rspec/failure.rb +8 -1
- data/lib/rspec_documentation/spec.rb +1 -1
- data/lib/rspec_documentation.rb +7 -0
- data/lib/templates/layout.css.erb +9 -0
- data/lib/templates/layout.html.erb +7 -0
- data/lib/templates/modal_spec.html.erb +1 -1
- data/lib/templates/tabbed_spec.html.erb +1 -1
- data/rspec-documentation/pages/030-Examples/012-Regular it Blocks.md +2 -2
- data/rspec-documentation/pages/060-Configuration/020-Build Paths.md +2 -2
- data/rspec-documentation/pages/060-Configuration/040-Hooks.md +31 -0
- data/rspec-documentation/pages/070-Publishing.md +2 -2
- metadata +4 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 6eb4258635900a3617ddf6ab4cdfb7fe1d1cba62fbd8231f11437cf9b9734c6b
|
4
|
+
data.tar.gz: f5db6165cfd08d759765d4e50a0398bfdb0ab99dee84567fd535bd97cd30f0a4
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: e25685a33fb2cc2bace75aa20c72f2b33407f2edec5a14840163cced2662fd852d3c87f8e4b31741b15825311365348f22cf5754b1850ddec1196bba64181a02
|
7
|
+
data.tar.gz: 3678422ca81bc09c5cd68db061b6a81746d21fb848824e229369721e727ac01f4fa4e517263ef9d47b8f1457f336d7dd6a0fdea0ee6ed63e498d62995f7c4102
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -3,8 +3,11 @@
|
|
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
|
+
|
6
8
|
def initialize
|
7
9
|
@context_defined = false
|
10
|
+
@hooks = {}
|
8
11
|
end
|
9
12
|
|
10
13
|
def context_defined?
|
@@ -24,5 +27,9 @@ module RSpecDocumentation
|
|
24
27
|
@context_defined = true
|
25
28
|
::RSpec.shared_context('__rspec_documentation', &block)
|
26
29
|
end
|
30
|
+
|
31
|
+
def hook(name, &block)
|
32
|
+
hooks[name] = block
|
33
|
+
end
|
27
34
|
end
|
28
35
|
end
|
@@ -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
|
@@ -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
|
@@ -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,
|
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
|
@@ -45,6 +45,15 @@ body {
|
|
45
45
|
background-color: #fff;
|
46
46
|
}
|
47
47
|
|
48
|
+
table.rspec-documentation-table td, table.rspec-documentation-table th {
|
49
|
+
border: 1px solid #cdcdcd;
|
50
|
+
padding: 0.5rem 1rem;
|
51
|
+
}
|
52
|
+
|
53
|
+
[data-bs-theme="dark"] table.rspec-documentation-table td, [data-bs-theme="dark"] table.rspec-documentation-table th {
|
54
|
+
border: 1px solid #4e4e4e;
|
55
|
+
}
|
56
|
+
|
48
57
|
[data-bs-theme="dark"] .header-wrapper {
|
49
58
|
background-color: #212121;
|
50
59
|
}
|
@@ -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>
|
@@ -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>
|
@@ -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/
|
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/
|
32
|
+
View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/index.html
|
33
33
|
```
|
@@ -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. |
|
@@ -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
|
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.
|
4
|
+
version: 0.0.6
|
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-
|
11
|
+
date: 2023-06-10 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,7 @@ 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
|
234
236
|
- rspec-documentation/pages/070-Publishing.md
|
235
237
|
- rspec-documentation/pages/500-License.md
|
236
238
|
- rspec-documentation/spec_helper.rb
|