rspec-documentation 0.0.2 → 0.0.4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.rubocop.yml +1 -0
- data/Gemfile.lock +3 -3
- data/Makefile +9 -0
- data/README.md +17 -21
- data/exe/rspec-documentation +5 -1
- data/lib/rspec/documentation/version.rb +1 -1
- data/lib/rspec/documentation.rb +1 -51
- data/lib/rspec_documentation/configuration.rb +17 -4
- data/lib/rspec_documentation/document.rb +17 -5
- data/lib/rspec_documentation/documentation.rb +85 -0
- data/lib/rspec_documentation/formatters/ansi.rb +44 -0
- data/lib/rspec_documentation/formatters/html.rb +31 -0
- data/lib/rspec_documentation/formatters/json.rb +32 -0
- data/lib/rspec_documentation/formatters/ruby.rb +31 -0
- data/lib/rspec_documentation/formatters/yaml.rb +36 -0
- data/lib/rspec_documentation/formatters.rb +20 -0
- data/lib/rspec_documentation/html_element.rb +21 -18
- data/lib/rspec_documentation/javascript_bundle.rb +17 -0
- data/lib/rspec_documentation/page_collection.rb +24 -9
- data/lib/rspec_documentation/page_tree.rb +16 -8
- data/lib/rspec_documentation/page_tree_element.rb +31 -9
- data/lib/rspec_documentation/parsed_document.rb +5 -3
- data/lib/rspec_documentation/project_initialization.rb +52 -0
- data/lib/rspec_documentation/rspec/failure.rb +20 -5
- data/lib/rspec_documentation/rspec.rb +0 -2
- data/lib/rspec_documentation/spec.rb +58 -12
- data/lib/rspec_documentation/stylesheet_bundle.rb +17 -0
- data/lib/rspec_documentation/summary.rb +87 -0
- data/lib/rspec_documentation/util.rb +12 -0
- data/lib/rspec_documentation.rb +16 -3
- data/lib/templates/000-Introduction.md.erb +35 -0
- data/lib/templates/010-Usage.md.erb +3 -0
- data/lib/templates/500-License.md.erb +3 -0
- data/lib/templates/bootstrap.js.erb +7 -0
- data/lib/templates/footer.html.erb +5 -0
- data/lib/templates/header.html.erb +16 -3
- data/lib/templates/layout.css.erb +381 -2
- data/lib/templates/layout.html.erb +13 -82
- data/lib/templates/layout.js.erb +67 -0
- data/lib/templates/modal_spec.html.erb +51 -0
- data/lib/templates/moon.svg.erb +1 -0
- data/lib/templates/script_tags.html.erb +1 -0
- data/lib/templates/stylesheet_links.html.erb +1 -0
- data/lib/templates/sun.svg.erb +1 -0
- data/lib/templates/tabbed_spec.html.erb +12 -49
- data/lib/templates/themes/bootstrap.min.css +11 -0
- data/lib/templates/themes/cerulean.css +5 -6
- data/lib/templates/themes/cosmo.css +5 -6
- data/lib/templates/themes/cyborg.css +5 -6
- data/lib/templates/themes/darkly.css +5 -6
- data/lib/templates/themes/flatly.css +5 -6
- data/lib/templates/themes/journal.css +5 -6
- data/lib/templates/themes/litera.css +5 -6
- data/lib/templates/themes/lumen.css +5 -6
- data/lib/templates/themes/lux.css +5 -6
- data/lib/templates/themes/materia.css +5 -6
- data/lib/templates/themes/minty.css +5 -6
- data/lib/templates/themes/morph.css +5 -6
- data/lib/templates/themes/pulse.css +5 -6
- data/lib/templates/themes/quartz.css +5 -6
- data/lib/templates/themes/sandstone.css +5 -6
- data/lib/templates/themes/simplex.css +5 -6
- data/lib/templates/themes/sketchy.css +5 -6
- data/lib/templates/themes/slate.css +5 -6
- data/lib/templates/themes/solar.css +5 -6
- data/lib/templates/themes/spacelab.css +5 -6
- data/lib/templates/themes/superhero.css +5 -6
- data/lib/templates/themes/united.css +5 -6
- data/lib/templates/themes/vapor.css +5 -6
- data/lib/templates/themes/yeti.css +5 -6
- data/lib/templates/themes/zephyr.css +5 -6
- data/rspec-documentation/pages/000-Introduction/000-Quickstart.md +17 -0
- data/rspec-documentation/pages/000-Introduction.md +14 -30
- data/rspec-documentation/pages/010-File System/000-Ordering.md +1 -1
- data/rspec-documentation/pages/010-File System/010-Documentation Bundle.md +9 -0
- data/rspec-documentation/pages/010-File System.md +1 -1
- data/rspec-documentation/pages/020-Running Tests.md +41 -0
- data/rspec-documentation/pages/030-Examples/010-Basic.md +51 -0
- data/rspec-documentation/pages/030-Examples/020-HTML.md +45 -0
- data/rspec-documentation/pages/030-Examples/030-ANSI.md +33 -0
- data/rspec-documentation/pages/030-Examples/040-JSON.md +39 -0
- data/rspec-documentation/pages/030-Examples/050-YAML.md +40 -0
- data/rspec-documentation/pages/030-Examples.md +7 -0
- data/rspec-documentation/pages/040-Spec Helper.md +11 -0
- data/rspec-documentation/pages/050-Linking.md +20 -0
- data/rspec-documentation/pages/060-Configuration/010-Context.md +26 -0
- data/rspec-documentation/pages/060-Configuration/020-Build Paths.md +33 -0
- data/rspec-documentation/pages/060-Configuration/030-Attribution.md +23 -0
- data/rspec-documentation/pages/060-Configuration.md +13 -0
- data/rspec-documentation/pages/070-Publishing.md +13 -0
- data/rspec-documentation/pages/500-License.md +11 -0
- data/rspec-documentation/spec_helper.rb +8 -0
- data/rspec-documentation.gemspec +2 -1
- metadata +46 -12
- data/lib/rspec_documentation/ansi_html.rb +0 -28
- data/lib/rspec_documentation/context.rb +0 -44
- data/lib/rspec_documentation/rspec/example_group.rb +0 -26
- data/lib/rspec_documentation/rspec/reporter.rb +0 -45
- data/rspec-documentation/pages/010-File System/010-Standalone Directories.md +0 -17
- data/rspec-documentation/pages/010-File System/020-Standalone Directory/Example Page.md +0 -3
- data/rspec-documentation/pages/020-Running Specs.md +0 -11
@@ -0,0 +1,17 @@
|
|
1
|
+
# Quickstart
|
2
|
+
|
3
|
+
Install _RSpec Documentation_:
|
4
|
+
|
5
|
+
```console
|
6
|
+
$ gem install rspec-documentation
|
7
|
+
```
|
8
|
+
|
9
|
+
Initialize your project:
|
10
|
+
|
11
|
+
```console
|
12
|
+
$ rspec-documentation
|
13
|
+
```
|
14
|
+
|
15
|
+
A placeholder `000-Introduction.md` file with a basic example spec will be automatically generated.
|
16
|
+
|
17
|
+
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_.
|
@@ -1,39 +1,23 @@
|
|
1
1
|
# RSpec Documentation
|
2
2
|
|
3
|
-
_RSpec Documentation_ provides a simple but powerful system for generating _Ruby_ documentation using [_RSpec_](https://rspec.info/).
|
3
|
+
_RSpec Documentation_ provides a simple but powerful system for generating _Ruby_ documentation using [_RSpec_](https://rspec.info/), designed to help you ensure that all code examples in your documentation really work.
|
4
4
|
|
5
|
-
|
5
|
+
Here's an example:
|
6
6
|
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
* Syntax highlighting for _Ruby_ and _HTML_, auto-formatting of _HTML_ output.
|
12
|
-
* Outputs a static bundle of _HTML_ files that can be uploaded to e.g. [GitHub Pages](https://pages.github.com/).
|
13
|
-
* Simple extension to _RSpec_, just call `it_documents <object> do ...` to write a documentation test, no complex _DSL_ to learn.
|
14
|
-
|
15
|
-
This documentation was written using _RSpec Documentation_.
|
16
|
-
|
17
|
-
## Quick Example
|
7
|
+
```rspec
|
8
|
+
subject { 'my subject' }
|
9
|
+
it { is_expected.to eql 'my subject' }
|
10
|
+
```
|
18
11
|
|
19
|
-
|
20
|
-
html = <<~HTML
|
21
|
-
<table class="table">
|
22
|
-
<thead>
|
23
|
-
<tr><th>Heading 1</th><th>Heading 2</th></tr>
|
24
|
-
</thead>
|
25
|
-
<tbody>
|
26
|
-
<tr><td>Value 1</td><td>Value 2</td></tr>
|
27
|
-
<tr><td>Value 3</td><td>Value 4</td></tr>
|
28
|
-
</tbody>
|
29
|
-
</table>
|
30
|
-
HTML
|
12
|
+
And the _Markdown_ that created it:
|
31
13
|
|
32
|
-
|
33
|
-
|
34
|
-
|
14
|
+
````markdown
|
15
|
+
```rspec
|
16
|
+
subject { 'my subject' }
|
17
|
+
it { is_expected.to eql 'my subject' }
|
35
18
|
```
|
19
|
+
````
|
36
20
|
|
37
|
-
|
21
|
+
See the [Quickstart](introduction/quickstart.html) setup guide to build your first _RSpec Documentation_ project.
|
38
22
|
|
39
|
-
Browse the
|
23
|
+
Browse the [Examples](examples.html) to get a better idea of the typical usage patterns.
|
@@ -0,0 +1,9 @@
|
|
1
|
+
# Documentation Bundle
|
2
|
+
|
3
|
+
A documentation bundle containing static _HTML_ and a minified _Javascript_ / _CSS_ bundle is created inside your `rspec-documentation/` directory every time you run the `rspec-documentation` command.
|
4
|
+
|
5
|
+
It is recommended to add this `rspec-documentation/bundle/` to `.gitignore`, depending on your deployment setup.
|
6
|
+
|
7
|
+
The bundle can be deployed to any web server and has no dependencies on any system services, making it ideal for popular _CDN_ services like [Surge.sh](https://surge.sh/).
|
8
|
+
|
9
|
+
See [Build Paths documentation](../configuration/build-paths.html) for details on deploying the documentation bundle to a subdirectory (i.e. when you are not hosting your documentation at the root path of your web server).
|
@@ -0,0 +1,41 @@
|
|
1
|
+
# Running Tests
|
2
|
+
|
3
|
+
To run your test suite, just call the provided `rspec-documentation` command from your project directory:
|
4
|
+
|
5
|
+
```console
|
6
|
+
$ rspec-documentation
|
7
|
+
|
8
|
+
Running specs...
|
9
|
+
|
10
|
+
8 examples, 0 failures.
|
11
|
+
|
12
|
+
Created 5 pages.
|
13
|
+
|
14
|
+
View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/introduction.html
|
15
|
+
|
16
|
+
Total build time: 0.63 seconds, examples executed in 0.0018 seconds.
|
17
|
+
```
|
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' }
|
29
|
+
|
30
|
+
|
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
|
+
```
|
@@ -0,0 +1,51 @@
|
|
1
|
+
# Basic Examples
|
2
|
+
|
3
|
+
## One-liners
|
4
|
+
|
5
|
+
This example uses a regular ```` ```rspec ```` code block.
|
6
|
+
|
7
|
+
The spec defines a `subject`, a simple comparison is made on its value to satisfy the test, and the value of `subject` is viewable on the _Output_ tab.
|
8
|
+
|
9
|
+
Any _RSpec_ test is valid, including one-liner syntax like this:
|
10
|
+
|
11
|
+
### Markdown
|
12
|
+
|
13
|
+
````markdown
|
14
|
+
```rspec
|
15
|
+
subject { 'my value' }
|
16
|
+
|
17
|
+
it { is_expected.to eql 'my value' }
|
18
|
+
```
|
19
|
+
````
|
20
|
+
|
21
|
+
### Output
|
22
|
+
|
23
|
+
```rspec
|
24
|
+
subject { 'my value' }
|
25
|
+
|
26
|
+
it { is_expected.to eql 'my value' }
|
27
|
+
```
|
28
|
+
|
29
|
+
## Regular `it` blocks
|
30
|
+
|
31
|
+
### Markdown
|
32
|
+
|
33
|
+
````markdown
|
34
|
+
```rspec
|
35
|
+
subject { 'my value' }
|
36
|
+
|
37
|
+
it 'contains some expected text' do
|
38
|
+
expect(subject).to eql 'my value'
|
39
|
+
end
|
40
|
+
```
|
41
|
+
````
|
42
|
+
|
43
|
+
### Output
|
44
|
+
|
45
|
+
```rspec
|
46
|
+
subject { 'my other value' }
|
47
|
+
|
48
|
+
it 'contains some expected text' do
|
49
|
+
expect(subject).to include 'other value'
|
50
|
+
end
|
51
|
+
```
|
@@ -0,0 +1,45 @@
|
|
1
|
+
## HTML
|
2
|
+
|
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
|
+
|
5
|
+
## Markdown
|
6
|
+
|
7
|
+
````markdown
|
8
|
+
```rspec:html
|
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>
|
20
|
+
HTML
|
21
|
+
end
|
22
|
+
|
23
|
+
it { is_expected.to include 'Value 1' }
|
24
|
+
```
|
25
|
+
````
|
26
|
+
|
27
|
+
## Output
|
28
|
+
|
29
|
+
```rspec:html
|
30
|
+
subject do
|
31
|
+
<<~HTML
|
32
|
+
<table class="table">
|
33
|
+
<thead>
|
34
|
+
<tr><th>Heading 1</th><th>Heading 2</th></tr>
|
35
|
+
</thead>
|
36
|
+
<tbody>
|
37
|
+
<tr><td>Value 1</td><td>Value 2</td></tr>
|
38
|
+
<tr><td>Value 3</td><td>Value 4</td></tr>
|
39
|
+
</tbody>
|
40
|
+
</table>
|
41
|
+
HTML
|
42
|
+
end
|
43
|
+
|
44
|
+
it { is_expected.to include 'Value 1' }
|
45
|
+
```
|
@@ -0,0 +1,33 @@
|
|
1
|
+
# ANSI
|
2
|
+
|
3
|
+
If your code's output includes colors encoded with [ANSI Escape Codes](https://en.wikipedia.org/wiki/ANSI_escape_code) use the ```` ```rspec:ansi ```` formatter to translate the codes into _HTML_.
|
4
|
+
|
5
|
+
8-bit colors and _RGB_ color codes are supported.
|
6
|
+
|
7
|
+
## Markdown
|
8
|
+
|
9
|
+
````markdown
|
10
|
+
```rspec:ansi
|
11
|
+
subject do
|
12
|
+
"\e[34mfoo\e[0m\e[0m \e[32mbar \e[36mfoo, bar, baz\e[0m\e[32m with " \
|
13
|
+
"\e[36mqux\e[0m\e[32m and quux\e[0m\e[0m and corge with " \
|
14
|
+
"\e[38;5;153mpale blue and " \
|
15
|
+
"\e[38;2;235;12;186mRGB PINK\e[0m\e[0m"
|
16
|
+
end
|
17
|
+
|
18
|
+
it { is_expected.to include "\e[38;2;235;12;186mRGB PINK" }
|
19
|
+
```
|
20
|
+
````
|
21
|
+
|
22
|
+
## Output
|
23
|
+
|
24
|
+
```rspec:ansi
|
25
|
+
subject do
|
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"
|
30
|
+
end
|
31
|
+
|
32
|
+
it { is_expected.to include "\e[38;2;235;12;186mRGB PINK" }
|
33
|
+
```
|
@@ -0,0 +1,39 @@
|
|
1
|
+
# JSON
|
2
|
+
|
3
|
+
If your code outputs _JSON_, use the ```` ```rspec:json``` ```` formatter to prettify your _JSON_ output. Note that your code must produce a raw _JSON_ string in order to use this formatter, it does not convert _Ruby_ objects into _JSON_.
|
4
|
+
|
5
|
+
## Markdown
|
6
|
+
|
7
|
+
````markdown
|
8
|
+
```rspec:json
|
9
|
+
subject do
|
10
|
+
{
|
11
|
+
'key' => 'value',
|
12
|
+
'array' => [1, 2, 3],
|
13
|
+
'boolean' => true,
|
14
|
+
'otherBoolean' => false
|
15
|
+
}.to_json
|
16
|
+
end
|
17
|
+
|
18
|
+
it 'has expected key/value' do
|
19
|
+
expect(JSON.parse(subject)).to include({ 'key' => 'value' })
|
20
|
+
end
|
21
|
+
```
|
22
|
+
````
|
23
|
+
|
24
|
+
## Output
|
25
|
+
|
26
|
+
```rspec:json
|
27
|
+
subject do
|
28
|
+
{
|
29
|
+
'key' => 'value',
|
30
|
+
'array' => [1, 2, 3],
|
31
|
+
'boolean' => true,
|
32
|
+
'otherBoolean' => false
|
33
|
+
}.to_json
|
34
|
+
end
|
35
|
+
|
36
|
+
it 'has expected key/value' do
|
37
|
+
expect(JSON.parse(subject)).to include({ 'key' => 'value' })
|
38
|
+
end
|
39
|
+
```
|
@@ -0,0 +1,40 @@
|
|
1
|
+
# YAML
|
2
|
+
|
3
|
+
|
4
|
+
If your code outputs _YAML_, use the ```` ```rspec:yaml``` ```` formatter to prettify your _YAML_ output. Note that your code must produce a raw _YAML_ string in order to use this formatter, it does not convert _Ruby_ objects into _YAML_.
|
5
|
+
|
6
|
+
## Markdown
|
7
|
+
|
8
|
+
````markdown
|
9
|
+
```rspec:yaml
|
10
|
+
subject do
|
11
|
+
{
|
12
|
+
'key' => 'value',
|
13
|
+
'array' => [1, 2, 3],
|
14
|
+
'boolean' => true,
|
15
|
+
'otherBoolean' => false
|
16
|
+
}.to_yaml
|
17
|
+
end
|
18
|
+
|
19
|
+
it 'has expected key/value' do
|
20
|
+
expect(YAML.safe_load(subject)).to include({ 'key' => 'value' })
|
21
|
+
end
|
22
|
+
```
|
23
|
+
````
|
24
|
+
|
25
|
+
## Output
|
26
|
+
|
27
|
+
```rspec:yaml
|
28
|
+
subject do
|
29
|
+
{
|
30
|
+
'key' => 'value',
|
31
|
+
'array' => [1, 2, 3],
|
32
|
+
'boolean' => true,
|
33
|
+
'otherBoolean' => false
|
34
|
+
}.to_yaml
|
35
|
+
end
|
36
|
+
|
37
|
+
it 'has expected key/value' do
|
38
|
+
expect(YAML.safe_load(subject)).to include({ 'key' => 'value' })
|
39
|
+
end
|
40
|
+
```
|
@@ -0,0 +1,11 @@
|
|
1
|
+
# Spec Helper
|
2
|
+
|
3
|
+
_RSpec Documentation_ will load `rspec-documentation/spec_helper.rb` before running your test suite if it is present.
|
4
|
+
|
5
|
+
The default `spec/spec_helper.rb` is not loaded by _RSpec Documentation_ unless you explicitly load it from your documentation's `spec_helper.rb`.
|
6
|
+
|
7
|
+
This allows you to separate setup and teardown of your documentation environment in case you have different requirements for each context.
|
8
|
+
|
9
|
+
There is nothing special about _RSpec Documentation's_ `spec_helper.rb`, but you may want to use some of the available configuration provided.
|
10
|
+
|
11
|
+
See the [Configuration](configuration.html) documentation for more details.
|
@@ -0,0 +1,20 @@
|
|
1
|
+
# Linking
|
2
|
+
|
3
|
+
Linking to another file in your documentation is easy. Use relative paths and apply the following simple transformation to your `.md` filename:
|
4
|
+
|
5
|
+
* Convert spaces to dashes.
|
6
|
+
* Lower-case all alphabetical characters.
|
7
|
+
* Remove any numerical ordering prefixes (see [Ordering](ordering.html)).
|
8
|
+
* Swap the `.md` extension for `.html`.
|
9
|
+
|
10
|
+
## Example
|
11
|
+
|
12
|
+
Linking to the [Spec Helper](spec-helper.html) page using the following _Markdown_:
|
13
|
+
|
14
|
+
````markdown
|
15
|
+
# rspec-documentation/pages/050-Linking.md
|
16
|
+
|
17
|
+
Linking to the [Spec Helper](spec-helper.html) page using the following _Markdown_:
|
18
|
+
````
|
19
|
+
|
20
|
+
The original filename in this case is `040-Spec Helper.md`.
|
@@ -0,0 +1,26 @@
|
|
1
|
+
# Context
|
2
|
+
|
3
|
+
You may want to set up some default context that is available in every example so that you don't have to pollute each example with the same repeated code.
|
4
|
+
|
5
|
+
To do this, add the following configuration.
|
6
|
+
|
7
|
+
```ruby
|
8
|
+
RSpec::Documentation.configure do |config|
|
9
|
+
config.context do
|
10
|
+
let(:foo) { 'baz' }
|
11
|
+
let(:bar) { 'qux' }
|
12
|
+
end
|
13
|
+
end
|
14
|
+
```
|
15
|
+
|
16
|
+
`foo` and `baz` will now be available to all examples. Under the hood this is just an implicit `RSpec.shared_context` block that is automatically included in every example, so the `let` used here is the same `let` that you're already familiar with and has no hidden caveats.
|
17
|
+
|
18
|
+
Of course you can still configure `before(:each)` blocks to do setup using regular _RSpec_ configuration in your `rspec-documentation/spec_helper.rb`.
|
19
|
+
|
20
|
+
The below example demonstrates the above configuration in action:
|
21
|
+
|
22
|
+
```rspec
|
23
|
+
subject { "#{foo} #{bar}" }
|
24
|
+
|
25
|
+
it { is_expected.to eql 'baz qux' }
|
26
|
+
```
|
@@ -0,0 +1,33 @@
|
|
1
|
+
# Build Paths
|
2
|
+
|
3
|
+
A handful of environment variables are avaialable to control various build paths.
|
4
|
+
|
5
|
+
## `RSPEC_DOCUMENTATION_BUNDLE_PATH`
|
6
|
+
|
7
|
+
Set `RSPEC_DOCUMENTATION_BUNDLE_PATH` to output your documentation bundle to somewhere other than `rspec-documentation/bundle/`.
|
8
|
+
|
9
|
+
The target directory will always be emptied before generating the output documentation.
|
10
|
+
|
11
|
+
```console
|
12
|
+
$ RSPEC_DOCUMENTATION_BUNDLE_PATH=/tmp/my-documentation-bundle/ rspec-documentation
|
13
|
+
|
14
|
+
All specs passed.
|
15
|
+
|
16
|
+
Created 13 pages.
|
17
|
+
|
18
|
+
View your documentation here: /tmp/my-documentation-bundle/introduction.html
|
19
|
+
```
|
20
|
+
|
21
|
+
## `RSPEC_DOCUMENTATION_URL_ROOT`
|
22
|
+
|
23
|
+
Set `RSPEC_DOCUMENTATION_URL_ROOT` to define the base path that all assets and links should point to. For example, this documentation is deployed to [https://docs.bob.frl/rspec-documentation/](https://docs.bob.frl/rspec-documentation/) so the URL root is `/rspec-documentation`.
|
24
|
+
|
25
|
+
```console
|
26
|
+
$ RSPEC_DOCUMENTATION_URL_ROOT=/rspec-documentation rspec-documentation
|
27
|
+
|
28
|
+
All specs passed.
|
29
|
+
|
30
|
+
Created 13 pages.
|
31
|
+
|
32
|
+
View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/introduction.html
|
33
|
+
```
|
@@ -0,0 +1,23 @@
|
|
1
|
+
# Attribution
|
2
|
+
|
3
|
+
The default attribution is at the bottom of this page. You are free to either set your own custom attribution or remove it completely.
|
4
|
+
|
5
|
+
## Custom Attribution
|
6
|
+
|
7
|
+
```ruby
|
8
|
+
# rspec-documentation/spec_helper.rb
|
9
|
+
|
10
|
+
RSpec::Documentation.configure do |config|
|
11
|
+
config.attribution = 'Copyright ©2023 <a href="https://example.com/">Acme Inc.</a>'
|
12
|
+
end
|
13
|
+
```
|
14
|
+
|
15
|
+
## Remove Attribution
|
16
|
+
|
17
|
+
```ruby
|
18
|
+
# rspec-documentation/spec_helper.rb
|
19
|
+
|
20
|
+
RSpec::Documentation.configure do |config|
|
21
|
+
config.attribution = nil
|
22
|
+
end
|
23
|
+
```
|
@@ -0,0 +1,13 @@
|
|
1
|
+
# Configuration
|
2
|
+
|
3
|
+
Most _RSpec Documentation_ features work out of the box, but you may need to configure certain features if the default configuration doesn't suit your needs.
|
4
|
+
|
5
|
+
Create a [spec helper](spec-helper.html) and add the following block of code:
|
6
|
+
|
7
|
+
```ruby
|
8
|
+
RSpec::Documentation.configure do |config|
|
9
|
+
# your config goes here
|
10
|
+
end
|
11
|
+
```
|
12
|
+
|
13
|
+
See each section of the configuration documentation for available options.
|
@@ -0,0 +1,13 @@
|
|
1
|
+
# Publishing
|
2
|
+
|
3
|
+
It is beyond the scope of this documentation to provide detailed information about publishing to various content delivery networks and web servers, but you may find the below example useful:
|
4
|
+
|
5
|
+
|
6
|
+
```console
|
7
|
+
$ RSPEC_DOCUMENTATION_URL_ROOT='/rspec-documentation' rspec-documentation
|
8
|
+
$ rsync --delete -r rspec-documentation/bundle/ docs01.bob.frl:/mnt/docs/rspec-documentation/
|
9
|
+
```
|
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.
|
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.
|
@@ -0,0 +1,11 @@
|
|
1
|
+
# License
|
2
|
+
|
3
|
+
## MIT
|
4
|
+
|
5
|
+
Copyright 2023 Robert Farrell
|
6
|
+
|
7
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
8
|
+
|
9
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
10
|
+
|
11
|
+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/rspec-documentation.gemspec
CHANGED
@@ -7,6 +7,7 @@ Gem::Specification.new do |spec|
|
|
7
7
|
spec.version = RSpec::Documentation::VERSION
|
8
8
|
spec.authors = ['Bob Farrell']
|
9
9
|
spec.email = ['git@bob.frl']
|
10
|
+
spec.licenses = ['MIT']
|
10
11
|
|
11
12
|
spec.summary = 'RSpec documentation tool.'
|
12
13
|
spec.description = 'Generates documentation from RSpec code blocks in Markdown files.'
|
@@ -30,7 +31,7 @@ Gem::Specification.new do |spec|
|
|
30
31
|
spec.add_runtime_dependency 'htmlbeautifier', '~> 1.4'
|
31
32
|
spec.add_runtime_dependency 'kramdown', '~> 2.4'
|
32
33
|
spec.add_runtime_dependency 'kramdown-parser-gfm', '~> 1.1'
|
33
|
-
spec.add_runtime_dependency 'paintbrush', '~> 0.1.
|
34
|
+
spec.add_runtime_dependency 'paintbrush', '~> 0.1.3'
|
34
35
|
spec.add_runtime_dependency 'redcarpet', '~> 3.6'
|
35
36
|
spec.add_runtime_dependency 'rouge', '~> 4.1'
|
36
37
|
spec.add_runtime_dependency 'rspec', '~> 3.12'
|