rspec-documentation 0.0.6 → 0.0.8

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