rspec-documentation 0.0.6 → 0.0.8

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 (44) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop.yml +1 -0
  3. data/Gemfile +1 -0
  4. data/Gemfile.lock +15 -10
  5. data/README.md +1 -1
  6. data/exe/rspec-documentation +15 -0
  7. data/lib/rspec/documentation/version.rb +1 -1
  8. data/lib/rspec_documentation/configuration.rb +7 -0
  9. data/lib/rspec_documentation/document.rb +8 -1
  10. data/lib/rspec_documentation/documentation.rb +5 -6
  11. data/lib/rspec_documentation/formatters/html.rb +3 -1
  12. data/lib/rspec_documentation/kramdown_html_converter.rb +13 -0
  13. data/lib/rspec_documentation/page_collection.rb +3 -0
  14. data/lib/rspec_documentation/page_tree.rb +7 -3
  15. data/lib/rspec_documentation/page_tree_element.rb +1 -1
  16. data/lib/rspec_documentation/parsed_document.rb +38 -4
  17. data/lib/rspec_documentation/project_initialization.rb +8 -0
  18. data/lib/rspec_documentation/rspec/failure.rb +3 -3
  19. data/lib/rspec_documentation/util.rb +12 -2
  20. data/lib/templates/layout.css.erb +109 -5
  21. data/lib/templates/layout.html.erb +13 -4
  22. data/lib/templates/layout.js.erb +86 -4
  23. data/lib/templates/link.svg.erb +1 -0
  24. data/lib/templates/modal_spec.html.erb +5 -5
  25. data/lib/templates/spec_helper.rb.erb +25 -0
  26. data/lib/templates/tabbed_spec.html.erb +4 -4
  27. data/rspec-documentation/pages/001-Quickstart.md +9 -1
  28. data/rspec-documentation/pages/020-Running Tests.md +6 -21
  29. data/rspec-documentation/pages/030-Examples/012-Regular it Blocks.md +7 -7
  30. data/rspec-documentation/pages/030-Examples/020-HTML.md +14 -14
  31. data/rspec-documentation/pages/030-Examples/030-ANSI.md +3 -3
  32. data/rspec-documentation/pages/030-Examples/040-JSON.md +4 -4
  33. data/rspec-documentation/pages/030-Examples/050-YAML.md +4 -4
  34. data/rspec-documentation/pages/030-Examples/060-XML.md +4 -4
  35. data/rspec-documentation/pages/060-Configuration/Consistent Height.md +16 -0
  36. data/rspec-documentation/pages/060-Configuration/Index Search.md +13 -0
  37. data/rspec-documentation/pages/060-Configuration/Table of Contents.md +35 -0
  38. data/rspec-documentation/pages/080-Rubocop.md +36 -0
  39. data/rspec-documentation/spec_helper.rb +1 -0
  40. metadata +12 -6
  41. /data/rspec-documentation/pages/060-Configuration/{030-Attribution.md → Attribution.md} +0 -0
  42. /data/rspec-documentation/pages/060-Configuration/{020-Build Paths.md → Build Paths.md} +0 -0
  43. /data/rspec-documentation/pages/060-Configuration/{010-Context.md → Context.md} +0 -0
  44. /data/rspec-documentation/pages/060-Configuration/{040-Hooks.md → Hooks.md} +0 -0
@@ -1,10 +1,11 @@
1
1
  <%= RSpecDocumentation.template('bootstrap', :js).result %>
2
2
 
3
3
  (() => {
4
- const initPageTree = () => {
5
- const pageTree = document.querySelector('.page-tree');
4
+ const pageTree = document.querySelector('.page-tree');
5
+ const getParentElement = (element) => document.querySelector(element.dataset.parentId);
6
+ const pageSearchTokens = {};
6
7
 
7
- const getParentElement = (element) => document.querySelector(element.dataset.parentId);
8
+ const initPageTree = () => {
8
9
  const isRootElement = (element) => !getParentElement(element);
9
10
  const isChildActive = (element) => !!element.querySelectorAll('.active').length;
10
11
  const isSiblingActive = (element) => !!getParentElement(element).querySelectorAll('.active').length;
@@ -22,7 +23,14 @@
22
23
  const visibilityCriteria = [isRootElement, isSelfOrParentActive, isChildActive, isSiblingActive];
23
24
 
24
25
  pageTree.querySelectorAll('li').forEach((element) => {
25
- if (!visibilityCriteria.some((criterion) => criterion(element))) element.classList.add('d-none');
26
+ element.classList.remove('search-active');
27
+ pageSearchTokens[element.id] = JSON.parse(element.dataset.searchTokens);
28
+
29
+ if (!visibilityCriteria.some((criterion) => criterion(element))) {
30
+ element.classList.add('d-none');
31
+ } else {
32
+ element.classList.remove('d-none');
33
+ }
26
34
  });
27
35
  pageTree.classList.remove('hidden');
28
36
  };
@@ -62,6 +70,80 @@
62
70
  });
63
71
  });
64
72
 
73
+ initTableOfContents = () => {
74
+ const tableOfContents = document.querySelector('#markdown-toc');
75
+
76
+ if (!tableOfContents) return;
77
+
78
+ const wrapper = document.createElement('div');
79
+ const content = document.querySelector('div.content');
80
+ const title = document.createElement('div');
81
+
82
+ title.append('Links');
83
+ title.classList.add('title');
84
+ wrapper.append(title);
85
+ wrapper.append(tableOfContents);
86
+ wrapper.classList.add('table-of-contents-wrapper');
87
+ content.prepend(wrapper);
88
+ };
89
+
90
+ initIndexSearch = () => {
91
+ const indexSearch = document.querySelector('.index-search');
92
+ const indexSearchField = indexSearch.querySelector('input');
93
+ const getQueryTokens = () => indexSearchField.value.toLowerCase().split(/\s+/);
94
+
95
+ indexSearch.addEventListener('keyup', (ev) => {
96
+ if (ev.keyCode === 13) {
97
+ const anchor = pageTree.querySelector('li.search-active a');
98
+ if (anchor) window.location = anchor.href;
99
+ } else {
100
+ searchIndex(getQueryTokens());
101
+ }
102
+ });
103
+ indexSearch.addEventListener('change', (ev) => searchIndex(getQueryTokens()));
104
+
105
+ document.addEventListener('keydown', (ev) => {
106
+ if (ev.ctrlKey && ev.keyCode === 191) {
107
+ ev.preventDefault();
108
+ indexSearchField.focus();
109
+ }
110
+ });
111
+
112
+ searchIndex = (searchTokens) => {
113
+ if (!searchTokens.every((searchToken) => searchToken)) {
114
+ initPageTree();
115
+ return;
116
+ }
117
+
118
+ const unhideRecursively = (element) => {
119
+ const parentElement = getParentElement(element);
120
+
121
+ element.classList.remove('d-none');
122
+
123
+ if (parentElement) unhideRecursively(parentElement);
124
+ };
125
+
126
+ const getMatchingTokens = (tokens) => {
127
+ const anyMatchingTokens = (token) => tokens.some((expectedToken) => expectedToken.includes(token))
128
+ return searchTokens.filter((token) => anyMatchingTokens(token));
129
+ };
130
+
131
+ pageTree.querySelectorAll('li').forEach((element) => {
132
+ const elementSearchTokens = pageSearchTokens[element.id];
133
+
134
+ if (getMatchingTokens(elementSearchTokens).length) {
135
+ element.classList.add('search-active');
136
+ unhideRecursively(element);
137
+ } else {
138
+ element.classList.add('d-none');
139
+ element.classList.remove('search-active');
140
+ }
141
+ });
142
+ };
143
+ };
144
+
65
145
  initPageTree();
66
146
  initThemeSwitcher();
147
+ initTableOfContents();
148
+ initIndexSearch();
67
149
  })();
@@ -0,0 +1 @@
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>
@@ -2,14 +2,14 @@
2
2
  <div class="modal-dialog modal-xl" id="modal-dialog-<%= element_id %>">
3
3
  <div class="modal-content">
4
4
  <div class="modal-header">
5
- <h5 class="modal-title" id="modal-<%= element_id %>-side-by-side-label">Side-by-side view</h5>
5
+ <h5 class="no_toc modal-title" id="modal-<%= element_id %>-side-by-side-label">Side-by-side view</h5>
6
6
  <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
7
7
  </div>
8
8
  <div class="modal-body">
9
9
  <div class="container p-3">
10
10
  <div class="row border">
11
11
  <div class="col border">
12
- <h5>Spec</h5>
12
+ <h5 class="no_toc">Spec</h5>
13
13
  <hr/>
14
14
  <div class="p-3 mb-5 code highlight">
15
15
  <%= code_source %>
@@ -18,7 +18,7 @@
18
18
 
19
19
  <% unless prettified_output.nil? %>
20
20
  <div class="col border">
21
- <h5>Output</h5>
21
+ <h5 class="no_toc">Output</h5>
22
22
  <hr/>
23
23
  <div class="p-3 mb-5 code highlight">
24
24
  <%= prettified_output %>
@@ -28,9 +28,9 @@
28
28
 
29
29
  <div class="col border">
30
30
  <% if prettified_output.nil? %>
31
- <h5>Output</h5>
31
+ <h5 class="no_toc">Output</h5>
32
32
  <% else %>
33
- <h5>Rendered Output</h5>
33
+ <h5 class="no_toc">Rendered Output</h5>
34
34
  <% end %>
35
35
  <hr/>
36
36
  <div class="p-3 mb-5 border <%= render_raw? ? nil : 'code highlight' %>">
@@ -0,0 +1,25 @@
1
+ RSpec::Documentation.configure do |config|
2
+ # Force example tabs to have a consistent height to prevent content jumping.
3
+ # config.consistent_height = <%= RSpecDocumentation.configuration.consistent_height.inspect %>
4
+
5
+ # Set a maximum height for example tabs. Tabs will scroll if content exceeds this value.
6
+ # config.max_height = <%= RSpecDocumentation.configuration.max_height.inspect %>
7
+
8
+ # Enable or disable the table of contents for each page. This renders a list of all headings in
9
+ # the page, except the main heading.
10
+ # config.table_of_contents = <%= RSpecDocumentation.configuration.table_of_contents.inspect %>
11
+
12
+ # Enable or disable the index search above the navigation tree.
13
+ # config.index_search = <%= RSpecDocumentation.configuration.index_search.inspect %>
14
+
15
+ config.context do
16
+ # Define global context here, e.g. add some `let` blocks to make them available in every example.
17
+ #
18
+ # let(:foo) { 'bar' }
19
+ end
20
+ end
21
+
22
+ RSpec.configure do |config|
23
+ # Define RSpec configuration here.
24
+ # Note that your main `spec/spec_helper.rb` is not loaded unless you require it in this file.
25
+ end
@@ -5,7 +5,7 @@
5
5
  <ul class="nav nav-tabs" id="html-tabs-<%= element_id %>" role="tablist">
6
6
 
7
7
  <li class="nav-item" role="presentation">
8
- <button class="nav-link active"
8
+ <button class="no_toc nav-link active"
9
9
  id="code-source-<%= element_id %>-tab"
10
10
  data-bs-toggle="tab"
11
11
  data-bs-target="#code-source-<%= element_id %>"
@@ -17,7 +17,7 @@
17
17
 
18
18
  <% unless prettified_output.nil? %>
19
19
  <li class="nav-item" role="presentation">
20
- <button class="nav-link"
20
+ <button class="no_toc nav-link"
21
21
  id="html-source-<%= element_id %>-tab"
22
22
  data-bs-toggle="tab"
23
23
  data-bs-target="#html-source-<%= element_id %>"
@@ -29,7 +29,7 @@
29
29
  <% end %>
30
30
 
31
31
  <li class="nav-item" role="presentation">
32
- <button class="nav-link"
32
+ <button class="no_toc nav-link"
33
33
  id="rendered-<%= element_id %>-tab"
34
34
  data-bs-toggle="tab"
35
35
  data-bs-target="#rendered-<%= element_id %>"
@@ -40,7 +40,7 @@
40
40
  </li>
41
41
 
42
42
  <li class="nav-item bs-auto ms-auto mb-2">
43
- <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#modal-<%= element_id %>-side-by-side">
43
+ <button type="button" class="no_toc btn btn-primary" data-bs-toggle="modal" data-bs-target="#modal-<%= element_id %>-side-by-side">
44
44
  View Side-by-side
45
45
  </button>
46
46
  </li>
@@ -6,12 +6,20 @@ Install _RSpec Documentation_:
6
6
  $ gem install rspec-documentation
7
7
  ```
8
8
 
9
+ Or add to your `Gemfile`:
10
+
11
+ ```ruby
12
+ gem 'rspec-documentation'
13
+ ```
14
+
9
15
  Initialize your project:
10
16
 
11
17
  ```console
12
18
  $ rspec-documentation
13
19
  ```
14
20
 
15
- A placeholder `000-Introduction.md` file with a basic example spec will be automatically generated.
21
+ 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.
16
22
 
17
23
  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_.
24
+
25
+ Whenever you add a `.md` file to your `rpsec-documentation/pages` directory, run `rspec-documentation` again to re-build your documentation bundle.
@@ -16,26 +16,11 @@ Running specs...
16
16
  Total build time: 0.63 seconds, examples executed in 0.0018 seconds.
17
17
  ```
18
18
 
19
- Documentation will only be generated if all tests pass. A summary of failures is provided if the suite does not run successfully:
20
-
21
- ```console
22
- $ rspec-documentation
23
-
24
- rspec-documentation/pages/030-Examples/010-Basic.md:23
25
-
26
- subject { 'my value' }
27
-
28
- it { is_expected.to eql 'not my value' }
19
+ ## Options
29
20
 
21
+ The following command-line options are supported:
30
22
 
31
- expected: "not my value"
32
- got: "my value"
33
-
34
- (compared using eql?)
35
-
36
- 6 examples, 1 failure.
37
-
38
- Failed examples:
39
-
40
- rspec-documentation/pages/030-Examples/010-Basic.md:23
41
- ```
23
+ |Option|Variant|Description|
24
+ |-|-|-|
25
+ |`--fail-fast`|`-F`|Abort the run after the first failure.|
26
+ |`--backtrace`|`-b`|Enable full backtrace.|
@@ -1,23 +1,23 @@
1
- ## Regular `it` blocks
1
+ # Regular `it` blocks
2
2
 
3
- ### Markdown
3
+ ## Markdown
4
4
 
5
5
  ````markdown
6
6
  ```rspec
7
- subject { 'my other value' }
7
+ subject(:value) { 'my other value' }
8
8
 
9
9
  it 'contains some expected text' do
10
- expect(subject).to eql 'other value'
10
+ expect(subjvalue).to eql 'other value'
11
11
  end
12
12
  ```
13
13
  ````
14
14
 
15
- ### Output
15
+ ## Output
16
16
 
17
17
  ```rspec
18
- subject { 'my other value' }
18
+ subject(:value) { 'my other value' }
19
19
 
20
20
  it 'contains some expected text' do
21
- expect(subject).to include 'other value'
21
+ expect(value).to include 'other value'
22
22
  end
23
23
  ```
@@ -1,4 +1,4 @@
1
- ## HTML
1
+ # HTML
2
2
 
3
3
  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.
4
4
 
@@ -7,16 +7,16 @@ Setting the code block language to `rspec:html` indicates that the output should
7
7
  ````markdown
8
8
  ```rspec:html
9
9
  subject do
10
- <<~HTML
11
- <table class="table">
12
- <thead>
13
- <tr><th>Heading 1</th><th>Heading 2</th></tr>
14
- </thead>
15
- <tbody>
16
- <tr><td>Value 1</td><td>Value 2</td></tr>
17
- <tr><td>Value 3</td><td>Value 4</td></tr>
18
- </tbody>
19
- </table>
10
+ <<~HTML
11
+ <table class="table">
12
+ <thead>
13
+ <tr><th>Heading 1</th><th>Heading 2</th></tr>
14
+ </thead>
15
+ <tbody>
16
+ <tr><td>Value 1</td><td>Value 2</td></tr>
17
+ <tr><td>Value 3</td><td>Value 4</td></tr>
18
+ </tbody>
19
+ </table>
20
20
  HTML
21
21
  end
22
22
 
@@ -28,8 +28,8 @@ it { is_expected.to include 'Value 1' }
28
28
 
29
29
  ```rspec:html
30
30
  subject do
31
- <<~HTML
32
- <table class="table">
31
+ <<~HTML
32
+ <table class="table">
33
33
  <thead>
34
34
  <tr><th>Heading 1</th><th>Heading 2</th></tr>
35
35
  </thead>
@@ -37,7 +37,7 @@ subject do
37
37
  <tr><td>Value 1</td><td>Value 2</td></tr>
38
38
  <tr><td>Value 3</td><td>Value 4</td></tr>
39
39
  </tbody>
40
- </table>
40
+ </table>
41
41
  HTML
42
42
  end
43
43
 
@@ -24,9 +24,9 @@ it { is_expected.to include "\e[38;2;235;12;186mRGB PINK" }
24
24
  ```rspec:ansi
25
25
  subject do
26
26
  "\e[34mfoo\e[0m\e[0m \e[32mbar \e[36mfoo, bar, baz\e[0m\e[32m with " \
27
- "\e[36mqux\e[0m\e[32m and quux\e[0m\e[0m and corge with " \
28
- "\e[38;5;153mpale blue and " \
29
- "\e[38;2;235;12;186mRGB PINK\e[0m\e[0m"
27
+ "\e[36mqux\e[0m\e[32m and quux\e[0m\e[0m and corge with " \
28
+ "\e[38;5;153mpale blue and " \
29
+ "\e[38;2;235;12;186mRGB PINK\e[0m\e[0m"
30
30
  end
31
31
 
32
32
  it { is_expected.to include "\e[38;2;235;12;186mRGB PINK" }
@@ -6,7 +6,7 @@ If your code outputs _JSON_, use the ```` ```rspec:json ```` formatter to pretti
6
6
 
7
7
  ````markdown
8
8
  ```rspec:json
9
- subject do
9
+ subject(:json) do
10
10
  {
11
11
  'key' => 'value',
12
12
  'array' => [1, 2, 3],
@@ -16,7 +16,7 @@ subject do
16
16
  end
17
17
 
18
18
  it 'has expected key/value' do
19
- expect(JSON.parse(subject)).to include({ 'key' => 'value' })
19
+ expect(JSON.parse(json)).to include({ 'key' => 'value' })
20
20
  end
21
21
  ```
22
22
  ````
@@ -24,7 +24,7 @@ end
24
24
  ## Output
25
25
 
26
26
  ```rspec:json
27
- subject do
27
+ subject(:json) do
28
28
  {
29
29
  'key' => 'value',
30
30
  'array' => [1, 2, 3],
@@ -34,6 +34,6 @@ subject do
34
34
  end
35
35
 
36
36
  it 'has expected key/value' do
37
- expect(JSON.parse(subject)).to include({ 'key' => 'value' })
37
+ expect(JSON.parse(json)).to include({ 'key' => 'value' })
38
38
  end
39
39
  ```
@@ -6,7 +6,7 @@ If your code outputs _YAML_, use the ```` ```rspec:yaml ```` formatter to pretti
6
6
 
7
7
  ````markdown
8
8
  ```rspec:yaml
9
- subject do
9
+ subject(:yaml) do
10
10
  {
11
11
  'key' => 'value',
12
12
  'array' => [1, 2, 3],
@@ -16,7 +16,7 @@ subject do
16
16
  end
17
17
 
18
18
  it 'has expected key/value' do
19
- expect(YAML.safe_load(subject)).to include({ 'key' => 'value' })
19
+ expect(YAML.safe_load(yaml)).to include({ 'key' => 'value' })
20
20
  end
21
21
  ```
22
22
  ````
@@ -24,7 +24,7 @@ end
24
24
  ## Output
25
25
 
26
26
  ```rspec:yaml
27
- subject do
27
+ subject(:yaml) do
28
28
  {
29
29
  'key' => 'value',
30
30
  'array' => [1, 2, 3],
@@ -34,6 +34,6 @@ subject do
34
34
  end
35
35
 
36
36
  it 'has expected key/value' do
37
- expect(YAML.safe_load(subject)).to include({ 'key' => 'value' })
37
+ expect(YAML.safe_load(yaml)).to include({ 'key' => 'value' })
38
38
  end
39
39
  ```
@@ -6,10 +6,10 @@ If your code outputs _XML_, use the ```` ```rspec:xml ```` formatter to prettify
6
6
 
7
7
  ````markdown
8
8
  ```rspec:xml
9
- subject { '<?xml version="1.0" encoding="UTF-8"?><foo><bar>baz</bar></foo>' }
9
+ subject(:xml) { '<?xml version="1.0" encoding="UTF-8"?><foo><bar>baz</bar></foo>' }
10
10
 
11
11
  it 'has expected key/value' do
12
- expect(Nokogiri::XML.parse(subject).xpath('//foo/bar').text).to eql 'baz'
12
+ expect(Nokogiri::XML.parse(xml).xpath('//foo/bar').text).to eql 'baz'
13
13
  end
14
14
  ```
15
15
  ````
@@ -17,9 +17,9 @@ end
17
17
  ## Output
18
18
 
19
19
  ```rspec:xml
20
- subject { '<?xml version="1.0" encoding="UTF-8"?><foo><bar>baz</bar></foo>' }
20
+ subject(:xml) { '<?xml version="1.0" encoding="UTF-8"?><foo><bar>baz</bar></foo>' }
21
21
 
22
22
  it 'has expected key/value' do
23
- expect(Nokogiri::XML.parse(subject).xpath('//foo/bar').text).to eql 'baz'
23
+ expect(Nokogiri::XML.parse(xml).xpath('//foo/bar').text).to eql 'baz'
24
24
  end
25
25
  ```
@@ -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
+ ```
@@ -0,0 +1,13 @@
1
+ # Index Search
2
+
3
+ The index above the navigation tree is enabled by default.
4
+
5
+ To disable the index search, set `config.index_search = false`:
6
+
7
+ ```ruby
8
+ # rspec-documentation/spec_helper.rb
9
+
10
+ RSpec::Documentation.configure do |config|
11
+ config.index_search = false
12
+ end
13
+ ```
@@ -0,0 +1,35 @@
1
+ # Table of Contents
2
+
3
+ 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).
4
+
5
+ To disable the table of contents, set `config.table_of_contents` to `false`:
6
+
7
+ ```ruby
8
+ # spec/spec_helper.rb
9
+
10
+ RSpec::Documentation.configure do |config|
11
+ config.table_of_contents = false # Default: true
12
+ end
13
+ ```
14
+
15
+ ## Overriding for Specific Pages
16
+
17
+ If you want to disable the Table of Contents globally but enable for specific pages, add the following anywhere in your _Markdown_ document:
18
+
19
+ ```markdown
20
+ * TOC
21
+ {:toc}
22
+ ```
23
+
24
+ ## Omit a Specific Header from Table of Contents
25
+
26
+ To omit a specific header element from the Table of Contents, add `{:.no_toc}` underneath the header:
27
+
28
+ ```markdown
29
+ ## Header included in Table of Contents
30
+
31
+ ## Header not included in Table of Contents
32
+ {:.no_toc}
33
+ ```
34
+
35
+ 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.
@@ -0,0 +1,36 @@
1
+ # RuboCop
2
+
3
+ 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.
4
+
5
+ It is highly recommended to use the official [`rubocop-rspec`](https://github.com/rubocop/rubocop-rspec) extension in conjunction with _RSpec::Documentation_.
6
+
7
+ ## Installation
8
+
9
+ Add the following to your `Gemfile`:
10
+
11
+ ```ruby
12
+ gem 'rubocop-rspec-documentation', require: false
13
+ ```
14
+
15
+ ## Configuration
16
+
17
+ Add the following configuration to your `.rubocop.yml` to enable the extension:
18
+
19
+ ```yaml
20
+ # .rubocop.yml
21
+
22
+ require:
23
+ - rubocop-rspec-documentation
24
+ ```
25
+
26
+ _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.
27
+
28
+ The following cops are disabled for your documentation examples as they cannot be sensibly addressed within each example:
29
+
30
+ * `Naming/FileName`
31
+ * `Gemspec/RequiredRubyVersion`
32
+ * `Style/FrozenStringLiteralComment`
33
+
34
+ ## Autocorrect
35
+
36
+ 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.
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require 'devpack'
3
4
  require 'nokogiri'
4
5
 
5
6
  RSpec::Documentation.configure do |config|
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.6
4
+ version: 0.0.8
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-10 00:00:00.000000000 Z
11
+ date: 2023-06-15 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: htmlbeautifier
@@ -177,9 +177,11 @@ files:
177
177
  - lib/templates/layout.css.erb
178
178
  - lib/templates/layout.html.erb
179
179
  - lib/templates/layout.js.erb
180
+ - lib/templates/link.svg.erb
180
181
  - lib/templates/modal_spec.html.erb
181
182
  - lib/templates/moon.svg.erb
182
183
  - lib/templates/script_tags.html.erb
184
+ - lib/templates/spec_helper.rb.erb
183
185
  - lib/templates/stylesheet_links.html.erb
184
186
  - lib/templates/sun.svg.erb
185
187
  - lib/templates/tabbed_spec.html.erb
@@ -229,11 +231,15 @@ files:
229
231
  - rspec-documentation/pages/040-Spec Helper.md
230
232
  - rspec-documentation/pages/050-Linking.md
231
233
  - rspec-documentation/pages/060-Configuration.md
232
- - rspec-documentation/pages/060-Configuration/010-Context.md
233
- - rspec-documentation/pages/060-Configuration/020-Build Paths.md
234
- - rspec-documentation/pages/060-Configuration/030-Attribution.md
235
- - rspec-documentation/pages/060-Configuration/040-Hooks.md
234
+ - rspec-documentation/pages/060-Configuration/Attribution.md
235
+ - rspec-documentation/pages/060-Configuration/Build Paths.md
236
+ - rspec-documentation/pages/060-Configuration/Consistent Height.md
237
+ - rspec-documentation/pages/060-Configuration/Context.md
238
+ - rspec-documentation/pages/060-Configuration/Hooks.md
239
+ - rspec-documentation/pages/060-Configuration/Index Search.md
240
+ - rspec-documentation/pages/060-Configuration/Table of Contents.md
236
241
  - rspec-documentation/pages/070-Publishing.md
242
+ - rspec-documentation/pages/080-Rubocop.md
237
243
  - rspec-documentation/pages/500-License.md
238
244
  - rspec-documentation/spec_helper.rb
239
245
  - sig/rspec/documentation.rbs