rspec-documentation 0.0.1 → 0.0.3

data/rspec-documentation/pages/010-File System/000-Ordering.md

@@ -0,0 +1,14 @@
+# Ordering
+
+If you want to specify a specific order that each item will appear in the documentation tree, simply prefix each file or directory with a number and a dash. The filename will be normalized when the documentation is generated.
+
+It is recommended to use increments of 10 when naming files to simplify re-ordering things later:
+
+```console
+rspec-documentation/
+└── pages/
+    ├── 000-Introduction.md
+    ├── 010-File System/
+    │   └── 000-Ordering.md
+    └── 010-File System.md
+```

data/rspec-documentation/pages/010-File System/010-Documentation Bundle.md

@@ -0,0 +1,9 @@
+# Documentation Bundle
+
+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.
+
+It is recommended to add this `rspec-documentation/bundle/` to `.gitignore`, depending on your deployment setup.
+
+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/).
+
+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).

data/rspec-documentation/pages/010-File System.md

@@ -0,0 +1,26 @@
+# File System
+
+The default directory where _RSpec Documentation_ will look for your _Markdown_ files is `rspec-documentation/pages`.
+
+Add as many files as you like and use you like into the root directory or subdirectories to generate the documentation tree.
+
+## Example Directory Structure
+
+```console
+rspec-documentation/
+└── pages/
+    ├── Introduction.md
+    ├── File System/
+    │   └── Ordering.md
+    └── File System.md
+```
+
+## Subdirectories
+
+Creating a subdirectory inside `rspec-documentation/pages` adds a new node to the index tree. Add files or more subdirectories to build the tree.
+
+The file you are reading now is located in `rspec-documentation/pages/File System.md`.
+
+There is also a directory named `rspec-documentation/pages/File System` which contains a file named `Ordering.md`.
+
+Take a look at the [source](https://github.com/bobf/rspec-documentation/blob/main/rspec-documentation/pages/) to see how it works.

data/rspec-documentation/pages/020-Running Tests.md

@@ -0,0 +1,41 @@
+# Running Tests
+
+To run your test suite, just call the provided `rspec-documentation` command from your project directory:
+
+```console
+$ rspec-documentation
+
+Running specs...
+
+  8 examples, 0 failures.
+
+  Created 5 pages.
+
+  View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/introduction.html
+
+  Total build time: 0.63 seconds, examples executed in 0.0018 seconds.
+```
+
+Documentation will only be generated if all tests pass. A summary of failures is provided if the suite does not run successfully:
+
+```console
+$ rspec-documentation
+
+    rspec-documentation/pages/030-Examples/010-Basic.md:23
+
+    subject { 'my value' }
+
+    it { is_expected.to eql 'not my value' }
+
+
+    expected: "not my value"
+         got: "my value"
+
+    (compared using eql?)
+
+6 examples, 1 failure.
+
+Failed examples:
+
+  rspec-documentation/pages/030-Examples/010-Basic.md:23
+```

data/rspec-documentation/pages/030-Examples/010-Basic.md

@@ -0,0 +1,51 @@
+# Basic Examples
+
+## One-liners
+
+This example uses a regular ```` ```rspec ```` code block.
+
+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.
+
+Any _RSpec_ test is valid, including one-liner syntax like this:
+
+### Markdown
+
+````markdown
+```rspec
+subject { 'my value' }
+
+it { is_expected.to eql 'my value' }
+```
+````
+
+### Output
+
+```rspec
+subject { 'my value' }
+
+it { is_expected.to eql 'my value' }
+```
+
+## Regular `it` blocks
+
+### Markdown
+
+````markdown
+```rspec
+subject { 'my value' }
+
+it 'contains some expected text' do
+  expect(subject).to eql 'my value'
+end
+```
+````
+
+### Output
+
+```rspec
+subject { 'my other value' }
+
+it 'contains some expected text' do
+  expect(subject).to include 'other value'
+end
+```

data/rspec-documentation/pages/030-Examples/020-HTML.md

@@ -0,0 +1,45 @@
+## HTML
+
+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.
+
+## Markdown
+
+````markdown
+```rspec:html
+subject do
+<<~HTML
+  <table class="table">
+    <thead>
+      <tr><th>Heading 1</th><th>Heading 2</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Value 1</td><td>Value 2</td></tr>
+      <tr><td>Value 3</td><td>Value 4</td></tr>
+    </tbody>
+  </table>
+  HTML
+end
+
+it { is_expected.to include 'Value 1' }
+```
+````
+
+## Output
+
+```rspec:html
+subject do
+<<~HTML
+  <table class="table">
+    <thead>
+      <tr><th>Heading 1</th><th>Heading 2</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Value 1</td><td>Value 2</td></tr>
+      <tr><td>Value 3</td><td>Value 4</td></tr>
+    </tbody>
+  </table>
+  HTML
+end
+
+it { is_expected.to include 'Value 1' }
+```

data/rspec-documentation/pages/030-Examples/030-ANSI.md

@@ -0,0 +1,33 @@
+# ANSI
+
+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_.
+
+8-bit colors and _RGB_ color codes are supported.
+
+## Markdown
+
+````markdown
+```rspec:ansi
+subject do
+  "\e[34mfoo\e[0m\e[0m \e[32mbar \e[36mfoo, bar, baz\e[0m\e[32m with " \
+  "\e[36mqux\e[0m\e[32m and quux\e[0m\e[0m and corge with " \
+  "\e[38;5;153mpale blue and " \
+  "\e[38;2;235;12;186mRGB PINK\e[0m\e[0m"
+end
+
+it { is_expected.to include "\e[38;2;235;12;186mRGB PINK" }
+```
+````
+
+## Output
+
+```rspec:ansi
+subject do
+  "\e[34mfoo\e[0m\e[0m \e[32mbar \e[36mfoo, bar, baz\e[0m\e[32m with " \
+  "\e[36mqux\e[0m\e[32m and quux\e[0m\e[0m and corge with " \
+  "\e[38;5;153mpale blue and " \
+  "\e[38;2;235;12;186mRGB PINK\e[0m\e[0m"
+end
+
+it { is_expected.to include "\e[38;2;235;12;186mRGB PINK" }
+```

data/rspec-documentation/pages/030-Examples/040-JSON.md

@@ -0,0 +1,39 @@
+# JSON
+
+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_.
+
+## Markdown
+
+````markdown
+```rspec:json
+subject do
+  {
+    'key' => 'value',
+    'array' => [1, 2, 3],
+    'boolean' => true,
+    'otherBoolean' => false
+  }.to_json
+end
+
+it 'has expected key/value' do
+  expect(JSON.parse(subject)).to include({ 'key' => 'value' })
+end
+```
+````
+
+## Output
+
+```rspec:json
+subject do
+  {
+    'key' => 'value',
+    'array' => [1, 2, 3],
+    'boolean' => true,
+    'otherBoolean' => false
+  }.to_json
+end
+
+it 'has expected key/value' do
+  expect(JSON.parse(subject)).to include({ 'key' => 'value' })
+end
+```

data/rspec-documentation/pages/030-Examples/050-YAML.md

@@ -0,0 +1,40 @@
+# YAML
+
+
+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_.
+
+## Markdown
+
+````markdown
+```rspec:yaml
+subject do
+  {
+    'key' => 'value',
+    'array' => [1, 2, 3],
+    'boolean' => true,
+    'otherBoolean' => false
+  }.to_yaml
+end
+
+it 'has expected key/value' do
+  expect(YAML.safe_load(subject)).to include({ 'key' => 'value' })
+end
+```
+````
+
+## Output
+
+```rspec:yaml
+subject do
+  {
+    'key' => 'value',
+    'array' => [1, 2, 3],
+    'boolean' => true,
+    'otherBoolean' => false
+  }.to_yaml
+end
+
+it 'has expected key/value' do
+  expect(YAML.safe_load(subject)).to include({ 'key' => 'value' })
+end
+```

data/rspec-documentation/pages/030-Examples.md

@@ -0,0 +1,7 @@
+# Examples
+
+See the provided examples to better understand _RSpec Documenation's_ features.
+
+For each example the raw _Markdown_ is included as well as the generated output.
+
+All examples are generated using _RSpec Documentation_.

data/rspec-documentation/pages/040-Spec Helper.md

@@ -0,0 +1,11 @@
+# Spec Helper
+
+_RSpec Documentation_ will load `rspec-documentation/spec_helper.rb` before running your test suite if it is present.
+
+The default `spec/spec_helper.rb` is not loaded by _RSpec Documentation_ unless you explicitly load it from your documentation's `spec_helper.rb`.
+
+This allows you to separate setup and teardown of your documentation environment in case you have different requirements for each context.
+
+There is nothing special about _RSpec Documentation's_ `spec_helper.rb`, but you may want to use some of the available configuration provided.
+
+See the [Configuration](configuration.html) documentation for more details.

data/rspec-documentation/pages/050-Linking.md

@@ -0,0 +1,20 @@
+# Linking
+
+Linking to another file in your documentation is easy. Use relative paths and apply the following simple transformation to your `.md` filename:
+
+* Convert spaces to dashes.
+* Lower-case all alphabetical characters.
+* Remove any numerical ordering prefixes (see [Ordering](ordering.html)).
+* Swap the `.md` extension for `.html`.
+
+## Example
+
+Linking to the [Spec Helper](spec-helper.html) page using the following _Markdown_:
+
+````markdown
+# rspec-documentation/pages/050-Linking.md
+
+Linking to the [Spec Helper](spec-helper.html) page using the following _Markdown_:
+````
+
+The original filename in this case is `040-Spec Helper.md`.

data/rspec-documentation/pages/060-Configuration/010-Context.md

@@ -0,0 +1,26 @@
+# Context
+
+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.
+
+To do this, add the following configuration.
+
+```ruby
+RSpec::Documentation.configure do |config|
+  config.context do
+    let(:foo) { 'baz' }
+    let(:bar) { 'qux' }
+  end
+end
+```
+
+`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.
+
+Of course you can still configure `before(:each)` blocks to do setup using regular _RSpec_ configuration in your `rspec-documentation/spec_helper.rb`.
+
+The below example demonstrates the above configuration in action:
+
+```rspec
+subject { "#{foo} #{bar}" }
+
+it { is_expected.to eql 'baz qux' }
+```

data/rspec-documentation/pages/060-Configuration/020-Build Paths.md

@@ -0,0 +1,33 @@
+# Build Paths
+
+A handful of environment variables are avaialable to control various build paths.
+
+## `RSPEC_DOCUMENTATION_BUNDLE_PATH`
+
+Set `RSPEC_DOCUMENTATION_BUNDLE_PATH` to output your documentation bundle to somewhere other than `rspec-documentation/bundle/`.
+
+The target directory will always be emptied before generating the output documentation.
+
+```console
+$ RSPEC_DOCUMENTATION_BUNDLE_PATH=/tmp/my-documentation-bundle/ rspec-documentation
+
+  All specs passed.
+
+  Created 13 pages.
+
+  View your documentation here: /tmp/my-documentation-bundle/introduction.html
+```
+
+## `RSPEC_DOCUMENTATION_URL_ROOT`
+
+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`.
+
+```console
+$ RSPEC_DOCUMENTATION_URL_ROOT=/rspec-documentation rspec-documentation
+
+  All specs passed.
+
+  Created 13 pages.
+
+  View your documentation here: /home/bob/dev/rspec-documentation/rspec-documentation/bundle/introduction.html
+```

data/rspec-documentation/pages/060-Configuration/030-Attribution.md

@@ -0,0 +1,23 @@
+# Attribution
+
+The default attribution is at the bottom of this page. You are free to either set your own custom attribution or remove it completely.
+
+## Custom Attribution
+
+```ruby
+# rspec-documentation/spec_helper.rb
+
+RSpec::Documentation.configure do |config|
+  config.attribution = 'Copyright &copy;2023 <a href="https://example.com/">Acme Inc.</a>'
+end
+```
+
+## Remove Attribution
+
+```ruby
+# rspec-documentation/spec_helper.rb
+
+RSpec::Documentation.configure do |config|
+  config.attribution = nil
+end
+```

data/rspec-documentation/pages/060-Configuration.md

@@ -0,0 +1,13 @@
+# Configuration
+
+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.
+
+Create a [spec helper](spec-helper.html) and add the following block of code:
+
+```ruby
+RSpec::Documentation.configure do |config|
+  # your config goes here
+end
+```
+
+See each section of the configuration documentation for available options.

data/rspec-documentation/pages/070-Publishing.md

@@ -0,0 +1,13 @@
+# Publishing
+
+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:
+
+
+```console
+$ RSPEC_DOCUMENTATION_URL_ROOT='/rspec-documentation' rspec-documentation
+$ rsync --delete -r rspec-documentation/bundle/ docs01.bob.frl:/mnt/docs/rspec-documentation/
+```
+
+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.
+
+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.

data/rspec-documentation/pages/500-License.md

@@ -0,0 +1,11 @@
+# License
+
+## MIT
+
+Copyright 2023 Robert Farrell
+
+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:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+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/spec_helper.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+RSpec::Documentation.configure do |config|
+  config.context do
+    let(:foo) { 'baz' }
+    let(:bar) { 'qux' }
+  end
+end

data/rspec-documentation.gemspec

@@ -4,9 +4,10 @@ require_relative 'lib/rspec/documentation/version'
 
 Gem::Specification.new do |spec|
   spec.name = 'rspec-documentation'
-  spec.version = Rspec::Documentation::VERSION
+  spec.version = RSpec::Documentation::VERSION
   spec.authors = ['Bob Farrell']
   spec.email = ['git@bob.frl']
+  spec.licenses = ['MIT']
 
   spec.summary = 'RSpec documentation tool.'
   spec.description = 'Generates documentation from RSpec code blocks in Markdown files.'
@@ -26,4 +27,12 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
   spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.add_runtime_dependency 'htmlbeautifier', '~> 1.4'
+  spec.add_runtime_dependency 'kramdown', '~> 2.4'
+  spec.add_runtime_dependency 'kramdown-parser-gfm', '~> 1.1'
+  spec.add_runtime_dependency 'paintbrush', '~> 0.1.3'
+  spec.add_runtime_dependency 'redcarpet', '~> 3.6'
+  spec.add_runtime_dependency 'rouge', '~> 4.1'
+  spec.add_runtime_dependency 'rspec', '~> 3.12'
 end

data/sig/rspec/documentation.rbs

@@ -1,4 +1,4 @@
-module Rspec
+module RSpec
   module Documentation
     VERSION: String
     # See the writing guide of rbs: https://github.com/ruby/rbs#guides