rspec-documentation 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1de5016a8e2e1a370ac923d9501c654c56e87e1f236f2f260ea634a8a28167b4
-  data.tar.gz: d75c74d43b80b502daa00778c3d4e8ede22514c2f500d67ee6dc31cb994772e3
+  metadata.gz: a964ddab12c98c8913f741374a4206eaff591787f10e692417d9cf097fd2fe45
+  data.tar.gz: 5dd25967d474700f60118b12649906f072bf912a173651bcf5ea1e70889c7ecb
 SHA512:
-  metadata.gz: 1bc358ecfcda3670c648dac2f11698facb57c2dc147826a87a26b24af07a1517fda6cd43431be25facb996280e7de50848630f0f8aab9ead11743ac1ec76e77e
-  data.tar.gz: a622ad2f53e2c743431678ed97e9a36a037c86f5b4b15c67c3eff439158ff0af026878be1f55a1aa5d4ee45b1a672a57db66c28912de012471d5bcd7aeedb6b1
+  metadata.gz: 1923b974e68f71be19dfeddc8379d242c54c3ce69770490399237897d46672177c15fa4990260bef4442414746e273e2e1f0764b67ac134a28c4d2c0a2336b09
+  data.tar.gz: 5f25067b064fa2acca91e6b82a45d1bf5218005885262b638589b0a94b746daf9c2c7da21b34b64865cec1e3d924c5f960adc30505c5ced25a146059c4a10bd6

data/.rubocop.yml

@@ -6,3 +6,4 @@ AllCops:
   NewCops: enable
   Exclude:
   - 'spec/fixtures/**/*'
+  - 'lib/rspec_documentation/page_tree.rb' # Rubocop bug, fixed in main

data/Gemfile.lock

@@ -1,11 +1,11 @@
 PATH
   remote: .
   specs:
-    rspec-documentation (0.0.2)
+    rspec-documentation (0.0.3)
       htmlbeautifier (~> 1.4)
       kramdown (~> 2.4)
       kramdown-parser-gfm (~> 1.1)
-      paintbrush (~> 0.1.1)
+      paintbrush (~> 0.1.3)
       redcarpet (~> 3.6)
       rouge (~> 4.1)
       rspec (~> 3.12)
@@ -26,7 +26,7 @@ GEM
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     paint (2.3.0)
-    paintbrush (0.1.1)
+    paintbrush (0.1.3)
     parallel (1.23.0)
     parser (3.2.2.1)
       ast (~> 2.4.1)

data/Makefile

@@ -1,5 +1,14 @@
+project=rspec-documentation
+
 .PHONY: test
 test:
 	bundle exec rspec
 	bundle exec rubocop
 	bundle exec strong_versions
+	exe/rspec-documentation
+
+.PHONY: publish
+publish:
+	@RSPEC_DOCUMENTATION_URL_ROOT='/$(project)' exe/rspec-documentation
+	@rsync --delete -r rspec-documentation/bundle/ docs01.bob.frl:/mnt/docs/$(project)/
+	@echo 'Published.'

data/README.md

@@ -1,31 +1,27 @@
 # RSpec::Documentation
 
-TODO: Delete this and the text below, and describe your gem
+_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.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rspec/documentation`. To experiment with that code, run `bin/console` for an interactive prompt.
+* Create a tree of _Markdown_ files in your project directory under `rspec-documentation/pages/`.
+* Embed tests in ```` ```rspec ```` code blocks (other output formatters are available - see examples).
+* Define a `subject` for each test.
+* Run the provided `rspec-documentation` command.
 
-## Installation
+There is no _DSL_ to learn and vanilla _RSpec_ examples are used to generate inputs and outputs. No _Markdown_ language extensions are used, simply define the language of a fenced code block as `rspec` in any `.md` file and _RSpecDocumentation_ will do the rest.
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Quick Example
 
-Install the gem and add to the application's Gemfile by executing:
+The following is an example _Markdown_ file.
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+````console
+# An example test
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+This is a very simple test:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```rspec
+subject { 'my subject' }
+it { is_expected.to eql 'my subject' }
+```
+````
 
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rspec-documentation.
+View the [full documentation](https://docs.bob.frl/rspec-documentation) (built using Rspec Documentation!) for detailed usage instructions.

data/exe/rspec-documentation

@@ -2,4 +2,16 @@
 # frozen_string_literal: true
 
 require_relative '../lib/rspec/documentation'
-RSpec::Documentation.generate_documentation
+
+# Try to load Rails and config/environment.rb, but don't panic if not present, we only use Rails
+# to fetch things like application name etc.
+begin
+  require 'rails'
+  require Pathname.new(Dir.pwd).join('config/environment')
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end
+
+documentation = RSpec::Documentation.generate_documentation
+
+exit 1 if documentation.failed?
+exit 0

data/lib/rspec/documentation/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Documentation
-    VERSION = '0.0.2'
+    VERSION = '0.0.3'
   end
 end

data/lib/rspec/documentation.rb

@@ -11,63 +11,13 @@ module RSpec
     class Error < StandardError; end
 
     class << self
-      include Paintbrush
-
       def generate_documentation
-        require_spec_helper
-        page_collection.generate
-        page_collection.flush unless failed?
-        print_summary
-        nil
-      end
-
-      def require_spec_helper
-        path = Pathname.new(Dir.pwd).join('rspec-documentation/spec_helper.rb')
-        require path if path.file?
+        RSpecDocumentation::Documentation.new.tap(&:generate)
       end
 
       def configure(&block)
         RSpecDocumentation.configure(&block)
       end
-
-      private
-
-      def print_success_summary
-        warn(paintbrush { green("\n  Created #{blue(page_paths.size)} pages.\n") })
-        warn(paintbrush { cyan("  View your documentation here: #{white(bundle_index_path)}\n") })
-      end
-
-      def print_failure_summary
-        page_collection.failures.each do |failure|
-          $stderr.write(failure.message)
-        end
-      end
-
-      def bundle_index_path
-        RSpecDocumentation::Util.bundle_dir.glob('*.html').first.expand_path
-      end
-
-      def page_paths
-        @page_paths ||= Pathname.new(Dir.pwd).join('rspec-documentation/pages').glob('**/*.md')
-      end
-
-      def page_collection
-        @page_collection ||= RSpecDocumentation::PageCollection.new(page_paths: page_paths)
-      end
-
-      def failed?
-        !page_collection.failures.empty?
-      end
-
-      def print_summary
-        if failed?
-          print_failure_summary
-        else
-          print_success_summary
-        end
-
-        nil
-      end
     end
   end
 end

data/lib/rspec_documentation/configuration.rb

@@ -4,12 +4,25 @@ module RSpecDocumentation
   # Configures the rspec-documentation gem, allows setting a context that makes values available to each example.
   class Configuration
     def initialize
-      @context = Context.new
+      @context_defined = false
     end
 
-    def context
-      yield @context if block_given?
-      @context
+    def context_defined?
+      @context_defined
+    end
+
+    def attribution
+      return @attribution if defined?(@attribution)
+
+      'Documentation generated by ' \
+        '<a target="_blank" href="https://github.com/bobf/rspec-documentation">rspec-documentation</a>'
+    end
+
+    def context(&block)
+      raise Error, 'RSpecDocumentation context has already been defined.' if context_defined?
+
+      @context_defined = true
+      ::RSpec.shared_context('__rspec_documentation', &block)
     end
   end
 end

data/lib/rspec_documentation/document.rb

@@ -5,8 +5,9 @@ module RSpecDocumentation
   class Document
     attr_reader :failures, :page_tree
 
-    def initialize(document:, page_tree:)
+    def initialize(document:, path:, page_tree:)
       @document = document
+      @path = path
       @page_tree = page_tree
       @failures = []
     end
@@ -30,7 +31,8 @@ module RSpecDocumentation
     end
 
     def title
-      # TODO: Try other methods of inferring documentation title, allow setting by configuration
+      return ::Rails.application.class.module_parent.name.titleize if defined?(::Rails)
+
       gem_spec&.name
     end
 
@@ -38,6 +40,10 @@ module RSpecDocumentation
       gem_spec&.version
     end
 
+    def homepage
+      gem_spec&.homepage
+    end
+
     def header
       RSpecDocumentation.template('header').result(binding)
     end
@@ -46,12 +52,20 @@ module RSpecDocumentation
       RSpecDocumentation.template('footer').result(binding)
     end
 
+    def stylesheet_bundle_href
+      Util.assets_root.join('bundle.css')
+    end
+
+    def javascript_bundle_src
+      Util.assets_root.join('bundle.js')
+    end
+
     private
 
-    attr_reader :document
+    attr_reader :document, :path
 
     def parsed_document
-      @parsed_document ||= ParsedDocument.new(document)
+      @parsed_document ||= ParsedDocument.new(document, path: path)
     end
 
     def gem_spec

data/lib/rspec_documentation/documentation.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Generates documentation from Markdown files, main entry point to documentation generator.
+  class Documentation
+    include Paintbrush
+
+    def generate
+      initialize_if_empty
+      start
+      require_spec_helper
+      ensure_context
+      page_collection.generate
+      flush unless failed?
+      summary.flush
+    rescue RSpecDocumentation::MissingFileError => e
+      warn(paintbrush { red e.message })
+      @failed = true
+    end
+
+    def failed?
+      @failed || !page_collection.failures.empty?
+    end
+
+    private
+
+    def require_spec_helper
+      path = pwd.join('rspec-documentation/spec_helper.rb')
+      require path if path.file?
+    end
+
+    # Ensure `__rspec_documentation` shared context is always defined.
+    # See lib/rspec_documenation/spec.rb
+    def ensure_context
+      return if RSpecDocumentation.configuration.context_defined?
+
+      RSpecDocumentation.configuration.context {} # rubocop:disable Lint/EmptyBlock
+    end
+
+    def start
+      warn(paintbrush { white "\nRunning specs..." })
+      @started_at = Time.now.utc
+    end
+
+    def initialize_if_empty
+      return if Util.base_dir.exist?
+
+      ProjectInitialization.new.flush
+    end
+
+    def summary
+      @summary ||= RSpecDocumentation::Summary.new(
+        page_collection: page_collection,
+        pwd: pwd,
+        started_at: @started_at
+      )
+    end
+
+    def flush
+      page_collection.flush
+      stylesheet_bundle.flush
+      javascript_bundle.flush
+    end
+
+    def stylesheet_bundle
+      @stylesheet_bundle ||= RSpecDocumentation::StylesheetBundle.new
+    end
+
+    def javascript_bundle
+      @javascript_bundle ||= RSpecDocumentation::JavascriptBundle.new
+    end
+
+    def page_paths
+      @page_paths ||= pwd.join('rspec-documentation/pages').glob('**/*.md')
+    end
+
+    def page_collection
+      @page_collection ||= RSpecDocumentation::PageCollection.new(page_paths: page_paths)
+    end
+
+    def pwd
+      @pwd ||= Pathname.new(Dir.pwd)
+    end
+  end
+end

data/lib/rspec_documentation/formatters/ansi.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    COLOR_CODES = [0, 1, 2, 3, 4, 5, 6, 7, 9].freeze
+
+    # Outputs a string containing ANSI color code escape sequences into HTML with attached
+    # classes for each matched color code. Cleans any remaining escape codes.
+    class Ansi
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        nil
+      end
+
+      def rendered_output
+        "<div class='ansi-html border m-1 p-4'><span>#{subbed_content}</span></div>"
+      end
+
+      def render_raw?
+        false
+      end
+
+      private
+
+      attr_reader :subject
+
+      def subbed_content
+        COLOR_CODES.reduce(subbed_hex_codes) do |string, color_code|
+          string&.gsub("\e[3#{color_code}m", "</span><span class='ansi-color-#{color_code}'>")
+                &.gsub("\e[9#{color_code}m", "</span><span class='ansi-bright ansi-color-#{color_code}'>")
+                &.gsub(/\e\[38;5;([0-9]{1,3})m/, "</span><span class='ansi-color-\\1'>")
+                &.gsub("\e[0m", "</span><span class='ansi-color-reset'>")
+        end&.gsub(/\e\[[0-9;]+m/, '')
+      end
+
+      def subbed_hex_codes
+        subject&.gsub(/\e\[38;2;([0-9]+);([0-9]+);([0-9]+)m/, '</span><span style="color: rgb(\1,\2,\3)">')
+      end
+    end
+  end
+end

data/lib/rspec_documentation/formatters/html.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    # Beautifies HTML received from a `subject`, renders the raw subject to be inserted directly
+    # into the output document.
+    class Html
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        formatter = Rouge::Formatters::HTML.new
+        lexer = Rouge::Lexers::HTML.new
+        formatter.format(lexer.lex(HtmlBeautifier.beautify(subject)))
+      end
+
+      def rendered_output
+        subject
+      end
+
+      def render_raw?
+        true
+      end
+
+      private
+
+      attr_reader :subject
+    end
+  end
+end

data/lib/rspec_documentation/formatters/json.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    # Produces prettified JSON to from an RSpec `subject` value.
+    class Json
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        nil
+      end
+
+      def rendered_output
+        formatter = Rouge::Formatters::HTML.new
+        lexer = Rouge::Lexers::JSON.new
+        formatter.format(lexer.lex(JSON.pretty_generate(JSON.parse(subject))))
+      rescue JSON::ParserError => e
+        raise Error, "Expected JSON for:\n#{subject}\n\nParser Error: #{e}"
+      end
+
+      def render_raw?
+        false
+      end
+
+      private
+
+      attr_reader :subject
+    end
+  end
+end

data/lib/rspec_documentation/formatters/ruby.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    # Default formatter for all RSpec examples. Used by all examples to generate the "Spec" tab
+    # content, i.e. the original source of the example code.
+    class Ruby
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        nil
+      end
+
+      def rendered_output
+        formatter = Rouge::Formatters::HTML.new
+        lexer = Rouge::Lexers::Ruby.new
+        formatter.format(lexer.lex(subject.inspect))
+      end
+
+      def render_raw?
+        false
+      end
+
+      private
+
+      attr_reader :subject
+    end
+  end
+end

data/lib/rspec_documentation/formatters/yaml.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    # Produces prettified YAML to from an RSpec `subject` value.
+    class Yaml
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        nil
+      end
+
+      def rendered_output
+        formatter = Rouge::Formatters::HTML.new
+        lexer = Rouge::Lexers::YAML.new
+        formatter.format(lexer.lex(YAML.safe_load(subject, permitted_classes: permitted_classes).to_yaml))
+      rescue Psych::SyntaxError => e
+        raise Error, "Expected YAML for:\n#{subject}\n\nSyntax Error: #{e}"
+      end
+
+      def render_raw?
+        false
+      end
+
+      private
+
+      attr_reader :subject
+
+      def permitted_classes
+        [Symbol, Date, Time, DateTime]
+      end
+    end
+  end
+end

data/lib/rspec_documentation/formatters.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'formatters/ruby'
+require_relative 'formatters/html'
+require_relative 'formatters/ansi'
+require_relative 'formatters/json'
+require_relative 'formatters/yaml'
+
+module RSpecDocumentation
+  # Provides a set of formatters for rendering the value of a `subject` in an RSpec example into
+  # a useful format according to the language specified in the relevant Markdown code block, e.g.
+  # `rspec:html` will use the `Html` formatter to render beautified HTML source and the rendered
+  # output.
+  module Formatters
+    def self.with_translated_html_entities(content)
+      content&.gsub("\n", '<br/>')
+             &.gsub('  ', '&nbsp;&nbsp;')
+    end
+  end
+end

data/lib/rspec_documentation/html_element.rb

@@ -14,24 +14,24 @@ module RSpecDocumentation
       Kramdown::Document.new(tabbed_spec, input: 'html').root
     end
 
-    def html_source
-      return nil unless spec.format == :html
-
+    def code_source
       formatter = Rouge::Formatters::HTML.new
-      lexer = Rouge::Lexers::HTML.new
-
-      formatter.format(lexer.lex(HtmlBeautifier.beautify(spec.described_object)))
+      lexer = Rouge::Lexers::Ruby.new
+      Formatters.with_translated_html_entities(formatter.format(lexer.lex(spec.source)))
     end
 
-    def code_source
-      formatted_ruby(spec.source)
+    def prettified_output
+      Formatters.with_translated_html_entities(formatter.prettified_output)
     end
 
-    def rendered_result
-      return spec.described_object if spec.format == :html
-      return AnsiHTML.new(spec.described_object).render if spec.format == :ansi
+    def rendered_output
+      return formatter.rendered_output if render_raw?
+
+      Formatters.with_translated_html_entities(formatter.rendered_output)
+    end
 
-      formatted_ruby(spec.described_object.inspect)
+    def render_raw?
+      formatter.render_raw?
     end
 
     def element_id
@@ -42,14 +42,17 @@ module RSpecDocumentation
 
     attr_reader :spec
 
-    def tabbed_spec
-      RSpecDocumentation.template('tabbed_spec').result(binding)
+    def formatter
+      @formatter ||= {
+        html: Formatters::Html,
+        ansi: Formatters::Ansi,
+        json: Formatters::Json,
+        yaml: Formatters::Yaml
+      }.fetch(spec.format, Formatters::Ruby).new(subject: spec.subject)
     end
 
-    def formatted_ruby(code)
-      formatter = Rouge::Formatters::HTML.new
-      lexer = Rouge::Lexers::Ruby.new
-      formatter.format(lexer.lex(code))
+    def tabbed_spec
+      RSpecDocumentation.template('tabbed_spec').result(binding)
     end
   end
 end

data/lib/rspec_documentation/javascript_bundle.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Compiles Javascript assets into a single file.
+  class JavascriptBundle
+    def flush
+      Util.bundle_dir.join('assets').mkpath
+      javascript_bundle_path.write(RSpecDocumentation.template(:layout, :js).result(binding))
+    end
+
+    private
+
+    def javascript_bundle_path
+      Util.bundle_dir.join('assets/bundle.js')
+    end
+  end
+end