asciidoctor-doctest 2.0.0.beta.3 → 2.0.0.beta.4

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 22928854e2f234ef48e4ddf8180e8c0c94f82341
4
- data.tar.gz: 8b0c16c9b9373c95245c2a559363e1caf0e06618
3
+ metadata.gz: bde064e105bfbe66ef6457b1f30318dca3a8376a
4
+ data.tar.gz: f8fc3a4cf46648290eb70b462b210a91ae46331c
5
5
  SHA512:
6
- metadata.gz: d4d4ba60bd2919139cd2717d54696f967f423e0e6cdd2c264f5a7547c4bed6765a4c72f5c2efada82a7798fe3faf75cd650af08e6ad734805f055e091cad4724
7
- data.tar.gz: 8634445f1342b9cfdc5b86485d9bbf9b8568dfd0b22f57932cb829bb62b54ee5d2e4c5e5227666e9f59435183d3ca787ee32f22a3b91e46a7b5aedc633b02171
6
+ metadata.gz: c1c26f53f43f7de304d9921bc737b0978fe13e84b552f3aacb94331623cb13e7ab5a1f48cd69879ee3f23f0a97c86aa13152e35591b480c6c0c92ee66a239d4b
7
+ data.tar.gz: b81e1405c6b9c2ae6969f22419954f6200f36763aac8fff373d374c41c5a042ada975b9956b224f9ef98bef57545d7ef09697dc09b7c0ff8aec95d6f6c9ea9be
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'pathname'
2
3
 
3
4
  module Asciidoctor
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'asciidoctor'
2
3
  require 'asciidoctor/doctest/no_fallback_template_converter'
3
4
  require 'corefines'
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: false
1
2
  require 'corefines'
2
3
 
3
4
  using Corefines::Object[:blank?, :deep_dup, :instance_values]
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Asciidoctor::DocTest
2
4
  module Factory
3
5
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'asciidoctor'
2
3
  require 'corefines'
3
4
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: false
1
2
  require 'asciidoctor/doctest/html_normalizer'
2
3
  require 'corefines'
3
4
  require 'htmlbeautifier'
@@ -15,7 +16,7 @@ module Asciidoctor::DocTest
15
16
  end
16
17
 
17
18
  def convert_examples(input_exmpl, output_exmpl)
18
- opts = output_exmpl.opts.dup
19
+ opts = input_exmpl.opts.merge(output_exmpl.opts)
19
20
 
20
21
  # The header & footer are excluded by default; always enable for document examples.
21
22
  opts[:header_footer] ||= input_exmpl.name.start_with?('document')
@@ -24,10 +25,10 @@ module Asciidoctor::DocTest
24
25
  opts[:include] ||= (@paragraph_xpath if input_exmpl.name.start_with? 'inline_')
25
26
 
26
27
  actual = convert(input_exmpl.content, header_footer: opts[:header_footer])
27
- .then { |s| parse_html s, !opts[:header_footer] }
28
+ .then { |s| parse_html s }
28
29
  .then { |h| find_nodes h, opts[:include] }
29
30
  .then { |h| remove_nodes h, opts[:exclude] }
30
- .then { |h| normalize(h) }
31
+ .then { |h| normalize h }
31
32
 
32
33
  expected = normalize(output_exmpl.content)
33
34
 
@@ -38,7 +39,18 @@ module Asciidoctor::DocTest
38
39
 
39
40
  def normalize(content)
40
41
  content = parse_html(content) if content.is_a? String
41
- HtmlBeautifier.beautify(content.normalize!)
42
+
43
+ has_content_type = !!meta_content_type(content)
44
+ result = HtmlBeautifier.beautify(content.normalize!)
45
+
46
+ # XXX: Nokogiri injects meta tag with Content-Type into rendered HTML
47
+ # document. This nasty hack removes that tag from the result if not
48
+ # present in the original HTML.
49
+ if !has_content_type && content.is_a?(Nokogiri::HTML::Document)
50
+ result.sub!(/^\s*<meta http-equiv="Content-Type" content="[^"]+"\s*\/?>\n/i, '')
51
+ end
52
+
53
+ result
42
54
  end
43
55
 
44
56
  def find_nodes(html, xpaths)
@@ -56,8 +68,26 @@ module Asciidoctor::DocTest
56
68
  end
57
69
  end
58
70
 
59
- def parse_html(str, fragment = true)
60
- fragment ? ::Nokogiri::HTML.fragment(str) : ::Nokogiri::HTML.parse(str)
71
+ def parse_html(str)
72
+ if str =~ /^\s*<!DOCTYPE\s/
73
+ ::Nokogiri::HTML.parse(str)
74
+ else
75
+ ::Nokogiri::HTML.fragment(str)
76
+ end
77
+ end
78
+
79
+ private
80
+
81
+ ##
82
+ # Searches <tt><meta http-equiv="Content-Type" content="..."></tt>
83
+ # element in the given HTML document.
84
+ #
85
+ # @param html [Nokogiri::HTML::Document, Nokogiri::HTML::DocumentFragment]
86
+ # @return [Nokogiri::XML::Element, nil]
87
+ def meta_content_type(html)
88
+ html.xpath('//meta[@http-equiv and boolean(@content)]').find do |node|
89
+ node['http-equiv'] =~ /\AContent-Type\z/i
90
+ end
61
91
  end
62
92
  end
63
93
  end
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'corefines'
2
3
  require 'nokogiri'
3
4
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'asciidoctor/doctest/io/base'
2
3
  require 'asciidoctor/doctest/io/asciidoc'
3
4
  require 'asciidoctor/doctest/io/xml'
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: false
1
2
  require 'asciidoctor/doctest/io/base'
2
3
  require 'corefines'
3
4
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: false
1
2
  require 'corefines'
2
3
  require 'pathname'
3
4
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: false
1
2
  require 'asciidoctor/doctest/io/base'
2
3
  require 'corefines'
3
4
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'corefines'
2
3
  require 'diffy'
3
4
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'asciidoctor/converter/template'
2
3
  require 'delegate'
3
4
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'asciidoctor/doctest/asciidoc_converter'
2
3
  require 'asciidoctor/doctest/generator'
3
4
  require 'asciidoctor/doctest/test_reporter'
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: false
1
2
  # coding: utf-8
2
3
  require 'minitest'
3
4
 
@@ -1,3 +1,4 @@
1
+ # frozen_string_literal: true
1
2
  require 'asciidoctor/doctest/minitest_diffy'
2
3
  require 'asciidoctor/doctest/test_reporter'
3
4
  require 'corefines'
@@ -1,5 +1,7 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Asciidoctor
2
4
  module DocTest
3
- VERSION = '2.0.0.beta.3'
5
+ VERSION = '2.0.0.beta.4'
4
6
  end
5
7
  end
@@ -1,5 +1,7 @@
1
1
  require 'forwardable'
2
2
 
3
+ using Corefines::String::unindent
4
+
3
5
  module DocTest
4
6
  describe HTML::Converter do
5
7
  extend Forwardable
@@ -10,9 +12,11 @@ module DocTest
10
12
 
11
13
  describe '#convert_examples' do
12
14
 
13
- let(:input) { Example.new 's:dummy', content: '*chunky* bacon' }
14
- let(:output) { Example.new 's:dummy', content: '<b>chunky</b> bacon', opts: opts }
15
- let(:opts) { {dummy: 'value'} }
15
+ let(:input) { Example.new 's:dummy', content: '*chunky* bacon', opts: input_opts }
16
+ let(:input_opts) { {} }
17
+ let(:output) { Example.new 's:dummy', content: output_content, opts: output_opts }
18
+ let(:output_content) { '<b>chunky</b> bacon' }
19
+ let(:output_opts) { {dummy: 'value'} }
16
20
  let(:converter_opts) { {header_footer: false} }
17
21
 
18
22
  subject(:result) { convert_examples input, output }
@@ -40,7 +44,7 @@ module DocTest
40
44
  it 'returns array of converted input content and output content'
41
45
 
42
46
  context 'with :exclude option' do
43
- let(:opts) { {exclude: ['.//p', './/code']} }
47
+ let(:output_opts) { {exclude: ['.//p', './/code']} }
44
48
 
45
49
  it 'returns content without HTML (sub)elements specified by XPath' do
46
50
  expect(result.first.gsub(/\s*/, '')).to eq \
@@ -49,7 +53,7 @@ module DocTest
49
53
  end
50
54
 
51
55
  context 'with :include option' do
52
- let(:opts) { {include: ['.//p']} }
56
+ let(:output_opts) { {include: ['.//p']} }
53
57
 
54
58
  it 'returns content with only HTML (sub)elements specified by XPath' do
55
59
  expect(result.first.gsub(/\s*/, '')).to eq '<p><b>Chunky</b>bacon</p><p>why?</p>'
@@ -57,11 +61,31 @@ module DocTest
57
61
  end
58
62
 
59
63
  context 'with :header_footer option' do
60
- let(:opts) { {header_footer: true} }
61
64
  let(:converter_opts) { {header_footer: true} }
62
65
 
63
- it 'renders content with :header_footer => true' do
64
- convert_examples input, output
66
+ context 'specified in output example' do
67
+ let(:output_opts) { {header_footer: true} }
68
+
69
+ it 'renders content with :header_footer => true' do
70
+ convert_examples input, output
71
+ end
72
+ end
73
+
74
+ context 'specified in input example' do
75
+ let(:input_opts) { {header_footer: true} }
76
+
77
+ it 'renders content with :header_footer => true' do
78
+ convert_examples input, output
79
+ end
80
+
81
+ context 'and disabled in output example' do
82
+ let(:output_opts) { {header_footer: false} }
83
+ let(:converter_opts) { {header_footer: false} }
84
+
85
+ it 'renders content with :header_footer => false' do
86
+ convert_examples input, output
87
+ end
88
+ end
65
89
  end
66
90
  end
67
91
 
@@ -83,13 +107,31 @@ module DocTest
83
107
  end
84
108
 
85
109
  context 'with :include option' do
86
- let(:opts) { {include: ['.//b']} }
110
+ let(:output_opts) { {include: ['.//b']} }
87
111
 
88
112
  it 'preferes the include option' do
89
113
  expect(result.first).to eq '<b>chunky</b>'
90
114
  end
91
115
  end
92
116
  end
117
+
118
+ context 'with output example including DOCTYPE' do
119
+ let :output_content do
120
+ <<-EOF.unindent.strip
121
+ <!DOCTYPE html>
122
+ <html>
123
+ <head>
124
+ <title>Test</title>
125
+ </head>
126
+ <body></body>
127
+ </html>
128
+ EOF
129
+ end
130
+
131
+ it 'returns expected content with DOCTYPE' do
132
+ expect(result.last).to eq output_content
133
+ end
134
+ end
93
135
  end
94
136
  end
95
137
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: asciidoctor-doctest
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.0.0.beta.3
4
+ version: 2.0.0.beta.4
5
5
  platform: ruby
6
6
  authors:
7
7
  - Jakub Jirutka
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2017-08-18 00:00:00.000000000 Z
11
+ date: 2017-08-21 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: asciidoctor
@@ -262,19 +262,13 @@ dependencies:
262
262
  - - "~>"
263
263
  - !ruby/object:Gem::Version
264
264
  version: '2.1'
265
- description: 'A tool for end-to-end testing of Asciidoctor backends based on comparing
266
- of textual output.
267
-
268
- '
265
+ description: |
266
+ A tool for end-to-end testing of Asciidoctor backends based on comparing of textual output.
269
267
  email: jakub@jirutka.cz
270
268
  executables: []
271
269
  extensions: []
272
270
  extra_rdoc_files: []
273
271
  files:
274
- - CHANGELOG.adoc
275
- - LICENSE
276
- - README.adoc
277
- - Rakefile
278
272
  - data/examples/asciidoc/admonition.adoc
279
273
  - data/examples/asciidoc/audio.adoc
280
274
  - data/examples/asciidoc/colist.adoc
data/CHANGELOG.adoc DELETED
@@ -1,58 +0,0 @@
1
- = Asciidoctor::DocTest Changelog
2
- :repo-uri: https://github.com/asciidoctor/asciidoctor-doctest
3
- :commit-uri: {repo-uri}/commit
4
- :issue-uri: {repo-uri}/issues
5
-
6
- This document provides a high-level view of the changes introduced in DocTest by release.
7
- For a detailed view of what has changed, refer to the {repo-uri}/commits/master[commit history] on GitHub.
8
-
9
-
10
- == 1.5.2.0 (2015-04-04)
11
-
12
- Improvements::
13
- * Update https://github.com/threedaymonk/htmlbeautifier[htmlbeautifier] to 1.0.0 and remove workaround in `html/html_beautifier` [{commit-uri}/6caafb0[6caafb0]].
14
- * Extract formatting (serialization) of example’s options into `BaseExamplesSuite#format_options` to be reusable [{commit-uri}/c4d779c[c4d779c]].
15
- * Implement serialization of examples suite into AsciiDoc [{commit-uri}/900aab8[900aab8]].
16
- * Replace custom core extensions, ActiveSupport and Colorize with https://github.com/jirutka/corefines[Corefines]. This also means that refinements will be used instead of global monkey-patching, when running on Ruby that supports refinements (currently MRI ≥2.1.0). [{commit-uri}/50e05c1[50e05c1], {commit-uri}/2f4a42e[2f4a42e]]
17
-
18
- Bug fixes::
19
- * Fix implementation of `eql?` and `hash` in BaseExample [{commit-uri}/c27615b[c27615b]].
20
-
21
-
22
- == 1.5.1.2 (2015-01-03)
23
-
24
- Improvements::
25
- * Support for MRI 2.0.0 and JRuby 9000-dev [{commit-uri}/8908c5d[8908c5d], {commit-uri}/748d54a[748d54a]].
26
-
27
-
28
- == 1.5.1.1 (2014-12-30)
29
-
30
- Bug fixes::
31
- * Avoid setting `backend_name` to an empty string.
32
- When there’s an empty string and code highlighter is set to Pygments or CodeRay, then Asciidoctor doesn’t highlight listings at all. [{commit-uri}/bf5f077[bf5f077]]
33
- * Update https://github.com/threedaymonk/htmlbeautifier[htmlbeautifier] to 0.0.11 that doesn’t modify content of `pre` element and adds newlines around block elements. {issue-uri}/3[#3] [{commit-uri}/4aaa137[4aaa137]]
34
-
35
-
36
- == 1.5.1 (2014-12-29)
37
-
38
- Improvements::
39
- * Rename parameter `renderer_opts` to `converter_opts` and method `render` to `convert` to be consistent with Asciidoctor (old names are aliased for now). {issue-uri}/2[#2] [{commit-uri}/97c06af[97c06af]]
40
- * Rename `to_s` to `content_pretty` in BaseExample and make alias. [{commit-uri}/3b610e2[3b610e2]]
41
-
42
- Bug fixes::
43
- * Allow to modify default `examples_path` in GeneratorTask (was frozen). [{commit-uri}/7251e6c[7251e6c]]
44
- * Fix `template_dirs` validation and default `backend_name` in AsciidocRenderer. [{commit-uri}/2a4413d[2a4413d]]
45
- * Beautify generated HTML examples. [{commit-uri}/e9d42be[e9d42be]]
46
- * Fix Generator to not lose description of the updated example. [{commit-uri}/0d2f4ee[0d2f4ee]]
47
-
48
- Tests::
49
- * Add end-to-end integration tests using Cucumber.
50
- * Increase (unit) test coverage from 84.2% to 88.5%.
51
-
52
- Known issues::
53
- * HTML beautifier doesn’t work as expected. {issue-uri}/3[#3]
54
-
55
-
56
- == 1.5.0 (2014-12-09)
57
-
58
- The first stable release.
data/LICENSE DELETED
@@ -1,21 +0,0 @@
1
- The MIT License
2
-
3
- Copyright 2014-2017 Jakub Jirutka <jakub@jirutka.cz> and the Asciidoctor Project.
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in
13
- all copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
- THE SOFTWARE.
data/README.adoc DELETED
@@ -1,312 +0,0 @@
1
- = Asciidoctor::DocTest
2
- Jakub Jirutka <https://github.com/jirutka[@jirutka]>
3
- :source-language: ruby
4
- // custom
5
- :gem-name: asciidoctor-doctest
6
- :gh-name: asciidoctor/{gem-name}
7
- :gh-branch: master
8
- :badge-style: flat
9
- :doctor-man-uri: http://asciidoctor.org/docs/user-manual
10
- :rawgit-base: https://cdn.rawgit.com/{gh-name}/master
11
- :src-base: lib/asciidoctor/doctest
12
-
13
- image:https://img.shields.io/travis/{gh-name}/{gh-branch}.svg?style={badge-style}[Build Status, link="https://travis-ci.org/{gh-name}"]
14
- image:https://img.shields.io/codeclimate/coverage/github/{gh-name}.svg?style={badge-style}[Test Coverage, link="https://codeclimate.com/github/{gh-name}"]
15
- image:https://img.shields.io/codeclimate/github/{gh-name}.svg?style={badge-style}[Code Climate, link="https://codeclimate.com/github/{gh-name}"]
16
- image:https://inch-ci.org/github/{gh-name}.svg?branch={gh-branch}&style={badge-style}[Inline docs, link="http://inch-ci.org/github/{gh-name}"]
17
- image:https://img.shields.io/gem/v/{gem-name}.svg?style={badge-style}[Gem Version, link="https://rubygems.org/gems/{gem-name}"]
18
- image:https://img.shields.io/badge/yard-docs-blue.svg?style={badge-style}[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/frames"]
19
-
20
- DocTest is a tool for end-to-end testing of Asciidoctor _backends_ based on comparing of textual output.
21
-
22
- It provides a collection of categorized <<input-examples, input _examples_>> (documents in AsciiDoc syntax) to simplify and systematize writing tests for new backends.
23
- You just write or <<generate-examples, generate>> the expected output, i.e. what the backend should produce for the given input.
24
-
25
- image::{rawgit-base}/doc/img/doctest-diag.svg[diagram, align="center"]
26
-
27
- Each example should be focused on one use case, so when writing a new backend, you can incrementally implement new features following the reference input examples.
28
- However, they are not strictly isolated like unit tests.
29
- For example, if you change a format of a paragraph, it may affect a variety of other examples.
30
-
31
- When test fails, DocTest prints a nicely formatted diff of the expected and actual output (see <<run-tests>>), so you see exactly what went wrong.
32
- Insignificant differences, such as attributes order in HTML, are ignored.
33
-
34
- DocTest supports HTML-based backends and can be easily <<how-to-extend-it, extended>> to support any other backend with textual output.
35
-
36
-
37
- == Setup DocTest
38
-
39
- Let’s say that you’re developing a new shiny HTML template-based backend named “shiny” and assume that you have templates in the directory `data/templates`.
40
-
41
- . Create a directory for your output examples:
42
- +
43
- [source, sh]
44
- mkdir -p test/examples/shiny
45
- +
46
- and optionally a directory for your extra input examples:
47
- +
48
- [source, sh]
49
- mkdir -p test/examples/asciidoc
50
-
51
- . Add development dependency on `asciidoctor-doctest` to your gemspec:
52
- +
53
- [source, ruby]
54
- s.add_development_dependency 'asciidoctor-doctest', '~> 2.0.0'
55
- +
56
- or Gemfile if you’re not distributing the backend as a gem:
57
- +
58
- [source, ruby]
59
- gem 'asciidoctor-doctest', '~> 2.0.0'
60
- +
61
- and run `bundle install`.
62
-
63
- . Create or edit `Rakefile` and configure DocTest tasks:
64
- +
65
- [source, ruby]
66
- ----
67
- require 'asciidoctor/doctest'
68
- require 'thread_safe'
69
- require 'tilt'
70
-
71
- DocTest::RakeTasks.new(:doctest) do |t|
72
- t.output_suite = DocTest::HTML::ExamplesSuite
73
- t.output_suite_opts = {
74
- examples_path: 'test/examples/shiny'
75
- }
76
- # add extra input examples (optional)
77
- t.input_suite_opts = {
78
- examples_path: [ *DocTest.examples_path, 'test/examples/asciidoc' ]
79
- }
80
- t.converter_opts = {
81
- template_dirs: 'data/templates'
82
- }
83
- end
84
- ----
85
-
86
- . Check if rake loads the DocTest tasks _doctest_, _doctest:test_ and _doctest:generate_.
87
- +
88
- [source, sh]
89
- bundle exec rake -D
90
-
91
-
92
- == Run tests
93
-
94
- Assume that you have defined the Rake tasks in the default namespace _doctest_ (see above).
95
- Then you can simply run:
96
-
97
- [source, sh]
98
- bundle exec rake doctest:test
99
-
100
- To test only specific examples, use `PATTERN` with glob-like expression:
101
-
102
- [source, sh]
103
- bundle exec rake doctest:test PATTERN='inline_*:*'
104
-
105
- For verbose output, use `VERBOSE=yes`:
106
-
107
- [source, sh]
108
- bundle exec rake doctest:test VERBOSE=yes
109
-
110
- image::doc/img/failing-test-term.gif[Failing test in term, align="center"]
111
-
112
-
113
- == Examples
114
-
115
- Test _example_ is just a document fragment in AsciiDoc syntax (a reference input), or the backend’s target syntax (an expected output).
116
- Example should consider one case of the generated output, i.e. it should reflect one code branch in a converter or template.
117
- Examples are grouped in _example groups_.
118
- Each group focuses on one block or inline element — more precisely Asciidoctor’s AST node (paragraph, table, anchor, footnote…).
119
-
120
- Examples group is a text file named similar to Asciidoctor templates, i.e. the AST node name with an extension according to syntax, for example `table.adoc`, `table.html`. See below for a list of the AST nodes.
121
- Individual examples in the group file are separated by a special header with the name of the example, an optional description and options.
122
-
123
- Each example is identified by its name and the group name like this: `{group_name}:{example_name}` (e.g. `table:with-title`).
124
- Input and output examples are paired — for every input example there should be an output example with the same identifier.
125
- When you <<run-tests, run tests>>, the input example is converted using the tested backend (or templates) and its actual output is compared with the expected output example.
126
-
127
- [horizontal]
128
- .List of Asciidoctor’s AST nodes
129
- document:: TODO
130
- embedded:: TODO
131
- section:: {doctor-man-uri}/#sections[document sections], i.e. headings
132
- admonition:: {doctor-man-uri}/#admonition[an admonition block]
133
- audio:: {doctor-man-uri}/#audio[an audio block]
134
- colist:: {doctor-man-uri}/#callouts[a code callouts] list
135
- dlist:: {doctor-man-uri}/#labeled-list[a labeled list] (aka definition list) and {doctor-man-uri}/#question-and-answer-style-list[a Q&A style list]
136
- example:: {doctor-man-uri}/#example[an example block]
137
- floating_title:: {doctor-man-uri}/#discrete-or-floating-section-titles[a discrete or floating section title]
138
- image:: {doctor-man-uri}/#images[an image block]
139
- listing:: {doctor-man-uri}/#listing-blocks[a listing and source code block]
140
- literal:: {doctor-man-uri}/#literal-text-and-blocks[a literal block]
141
- olist:: {doctor-man-uri}/#ordered-lists[an ordered list] (i.e. numbered list)
142
- open:: {doctor-man-uri}/#open-blocks[open blocks], {doctor-man-uri}/#user-abstractabstract[abstract], …
143
- outline:: an actual {doctor-man-uri}/#user-toc[TOC] content (i.e. list of links), usually recursively called
144
- page_break:: {doctor-man-uri}/#page-break[page break]
145
- paragraph:: {doctor-man-uri}/#paragraph[a paragraph]
146
- pass:: {doctor-man-uri}/#pass-bl[a passthrough block]
147
- preamble:: {doctor-man-uri}/#doc-preamble[a preamble], optionally with a TOC
148
- quote:: {doctor-man-uri}/#quote[a quote block]
149
- sidebar:: {doctor-man-uri}/#sidebar[a sidebar]
150
- stem:: {doctor-man-uri}/#stem[a STEM block] (Science, Technology, Engineering and Math)
151
- table:: {doctor-man-uri}/#tables[a table]
152
- thematic_break:: {doctor-man-uri}/#horizontal-rules[a thematic break] (i.e. horizontal rule)
153
- toc:: {doctor-man-uri}/#manual-placement[a TOC macro] (i.e. manually placed TOC); This block is used for `toc::[]` macro only and it’s responsible just for rendering of a the TOC “envelope,” not an actual TOC content.
154
- ulist:: {doctor-man-uri}/#unordered-lists[an unordered list] (aka bullet list) and a {doctor-man-uri}/#checklist[checklist] (e.g. TODO list)
155
- verse:: {doctor-man-uri}/#verse[a verse block]
156
- video:: {doctor-man-uri}/#video[a video block]
157
- inline_anchor:: {doctor-man-uri}/#url[anchors] (links, cross references and bibliography references)
158
- inline_break:: {doctor-man-uri}/#line-breaks[line break]
159
- inline_button:: {doctor-man-uri}/#ui-buttons[UI button]
160
- inline_callout:: {doctor-man-uri}/#callouts[code callout] icon/mark inside a code block
161
- inline_footnote:: {doctor-man-uri}/#user-footnotes[footnote]
162
- inline_image:: {doctor-man-uri}/#images[inline image] and {doctor-man-uri}/#inline-icons[inline icon]
163
- inline_kbd:: {doctor-man-uri}/#keyboard-shortcuts[keyboard shortcut]
164
- inline_menu:: {doctor-man-uri}/#menu-selections[menu section]
165
- inline_quoted:: {doctor-man-uri}/#quotes[text formatting]; emphasis, strong, monospaced, superscript, subscript, curved quotes and inline STEM
166
-
167
-
168
- === Input examples
169
-
170
- DocTest provides a collection of the reference input examples that should be suitable for most backends.
171
- You can find them in link:data/examples/asciidoc[].footnote:[Since GitHub implicitly renders them as a plain AsciiDoc, you must view a Raw source if you want to see what’s going on there.]
172
- There are a lot of test examples and some of them may not be relevant to your backend — that’s okay, when some output example is not found, it’s marked as skipped in test.
173
-
174
- You can also write your own input examples and use them together with those provided (or replace them).
175
- Just add another directory to your examples_path (e.g. `test/examples/asciidoc`) and create example group files with `.adoc` suffix here (e.g. `video.adoc`).
176
- When DocTest is looking for examples to test, it indexes all examples found in files with `.adoc` suffix on the examples_path.
177
- If there are two files with the same name, it simply merges their content, and if they contain two examples with the same name, then the first wins (i.e. that from the file that is ahead on the examples_path).
178
-
179
- ==== Format
180
-
181
- [source, asciidoc]
182
- ----
183
- // .first-example
184
- // Each block must be preceded by a header (comment); the first line must
185
- // contain the example’s name prefixed with a dot. This text is interpreted
186
- // as a description.
187
- The example’s content in *Asciidoc*.
188
-
189
- NOTE: The trailing new line (below this) will be removed.
190
-
191
- // .second-example
192
- * List item level 1
193
- ** List item level 2
194
-
195
- ----
196
-
197
- === HTML-based examples
198
-
199
- HtmlTest assumes that paragraphs are enclosed in `<p></p>` tags and implicitly sets the _include_ option to `./p/node()` for `inline_*:*` examples (if _include_ is not already set).
200
- If it’s not your case, then you must overwrite it:
201
-
202
- [source, ruby]
203
- ----
204
- DocTest::RakeTasks.new(:doctest) do |t|
205
- t.output_suite = DocTest::HTML::ExamplesSuite
206
- t.output_suite_opts = {
207
- examples_path: 'test/examples/shiny',
208
- paragraph_xpath: './div/p/node()' //<1>
209
- }
210
- t.converter_opts = {
211
- template_dirs: 'data/templates'
212
- }
213
- end
214
- ----
215
-
216
- ==== Options
217
-
218
- List of options that can be set in the header of HTML example.
219
-
220
- include::
221
- XPath expression that specifies a subsection of the document that should be
222
- compared (asserted). Default is `./p/node()` for `inline_*:*` groups and
223
- empty (i.e. `.`) for others.
224
- exclude::
225
- XPath expression that specifies parts of the document that should _not_ be
226
- compared (asserted). Always start the expression with a dot (e.g. `.//h1`).
227
- This option may be used multiple times per example.
228
- header_footer::
229
- Option for Asciidoctor to render a full document (instead of embedded).
230
- This is default for `document:*` group.
231
-
232
- ==== Format
233
-
234
- [source, html]
235
- ----
236
- <!-- .first-example
237
- Each example must be preceded by a header (comment); the first line must
238
- contain the example’s name prefixed with a dot. This text is interpreted
239
- as a description.
240
- -->
241
- <p>The example’s content in <strong>HTML</strong>.</p>
242
-
243
- <div class="note">The trailing new line (below this) will be removed.</div>
244
-
245
- <!-- .second-example
246
- You may also specify options for comparing or Asciidoctor renderer. Option
247
- line starts with a semicolon, then comes the option name ended by a
248
- semicolon and after that the option’s value (may be omitted for boolean
249
- options).
250
- :option_1: value 1
251
- :option_2: value 1
252
- :option_2: value 2
253
- :boolean_option:
254
- -->
255
- <div class="colist">
256
- <ol>
257
- <li>Method signature</li>
258
- <li>Some stuff inside</li>
259
- <li>Return statement</li>
260
- </ol>
261
- </div>
262
-
263
- ----
264
-
265
-
266
- === Generate examples
267
-
268
- Writing examples of an expected output for all the input examples from scratch is quite a chore.
269
- Therefore DocTest provides a generator.
270
- When you have at least partially working Asciidoctor _backend_ (converter or a set of templates), you can pass the input examples through it and generate your output examples.
271
- Then you should verify them and modify if needed.
272
-
273
- Assume that you have defined the Rake tasks in the default namespace _doctest_ (see <<setup-doctest>>).
274
-
275
- Now you can generate output examples from all the input examples (those with `.adoc` extension) found on the examples_path that doesn’t already exist (i.e. it doesn’t rewrite existing):
276
-
277
- [source, sh]
278
- bundle exec rake doctest:generate
279
-
280
- Same as previous, but rewrite existing tested examples:
281
-
282
- [source, sh]
283
- bundle exec rake doctest:generate FORCE=yes
284
-
285
- Generate just examples for `ulist` node (i.e. all examples in `ulist.adoc` file(s) found on the examples_path) that doesn’t exist yet:
286
-
287
- [source, sh]
288
- bundle exec rake doctest:generate PATTERN='ulist:*'
289
-
290
- (Re)generate examples which name starts with `basic` for all _inline_ nodes (i.e. files that starts with `inline_`):
291
-
292
- [source, sh]
293
- bundle exec rake doctest:generate PATTERN='inline_*:basic*' FORCE=yes
294
-
295
-
296
- == How to extend it
297
-
298
- You can extend DocTest to support any textual format you want.
299
- All what you need is to subclass link:{src-base}/base_examples_suite.rb[BaseExamplesSuite] and usually also link:{src-base}/base_example.rb[BaseExample].
300
-
301
-
302
- == Contributing
303
-
304
- . Fork it
305
- . Create your feature branch (`git checkout -b my-new-feature`)
306
- . Commit your changes (`git commit -am 'Add some feature'`)
307
- . Push to the branch (`git push origin my-new-feature`)
308
- . Create new Pull Request
309
-
310
- == License
311
-
312
- This project is licensed under http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.
data/Rakefile DELETED
@@ -1,37 +0,0 @@
1
- require 'rake/clean'
2
- require 'bundler/gem_tasks'
3
-
4
- default_tasks = []
5
-
6
- begin
7
- require 'rspec/core/rake_task'
8
-
9
- RSpec::Core::RakeTask.new(:spec)
10
-
11
- task :test => :spec
12
- default_tasks << :spec
13
- rescue LoadError => e
14
- warn "#{e.path} is not available"
15
- end
16
-
17
- begin
18
- require 'cucumber/rake/task'
19
-
20
- Cucumber::Rake::Task.new do |t|
21
- t.cucumber_opts = ['-r features/support', '--format pretty']
22
- end
23
-
24
- default_tasks << :cucumber
25
- rescue LoadError => e
26
- warn "#{e.path} is not available"
27
- end
28
-
29
- begin
30
- require 'yard'
31
- # options are defined in .yardopts
32
- YARD::Rake::YardocTask.new(:yard)
33
- rescue LoadError => e
34
- warn "#{e.path} is not available"
35
- end
36
-
37
- task :default => default_tasks