rdoc-markdown 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f34bf7fc9e0588740713d04925521cfc098ce43b057c16e55ed9bcfb5b16030f
-  data.tar.gz: 2180ab33878a7aa893dd9daded24048319a0670d7c7530789493d41f0fccdd6b
+  metadata.gz: cc9298f0cd81d54367d58d68aa1cacead0c80be2e43ea591f5fe4bbf29e44ca5
+  data.tar.gz: 15b4e889626b4b06fe2cd98e910f26d974d849690cb11a351e6fcceae55aeae1
 SHA512:
-  metadata.gz: 7de709a0032575a1720aa6c99be7ed712471dc02c9c99c5bdcfc2bc8035691d7b633a5431b3575767c648d36b74cf6380e0162085578a59d7367629de902232b
-  data.tar.gz: 4c8ff9eef4209d99aa9034ccf0e7ebaca5cc097316127ff24d4875d327595c28731e1dd44f39bb1f4e5367eead1c1348653d8f2cf5bae80d6d94afd093cf6ded
+  metadata.gz: 779545ebd9dfdb19e8c474ff3ae851586ac9bddf069e74a828fe9cc2c482e4c1ca22fd11330065c35419099612d8977001b63940d4f583d3f6de838ccdbde25d
+  data.tar.gz: 2f2306bff2ca81fd87487db0f771ce24ecd4fbe4ceb8dfe379b538ea2d11689c7d7133dd91f380ce9248bafd51d3ac09bb1477f18e7adde4731444092b296415

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.3.3)
+    rdoc-markdown (0.3.7)
       erb (~> 2.0)
       extralite-bundle (~> 1.0)
       rdoc (~> 6.0)
@@ -33,29 +33,29 @@ GEM
     rdiscount (2.2.7)
     rdoc (6.4.0)
       psych (>= 4.0.0)
-    regexp_parser (2.6.0)
+    regexp_parser (2.6.1)
     reverse_markdown (2.1.1)
       nokogiri
     rexml (3.2.5)
-    rubocop (1.35.1)
+    rubocop (1.39.0)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.20.1, < 2.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
     rubocop-ast (1.23.0)
       parser (>= 3.1.1.0)
-    rubocop-performance (1.14.3)
+    rubocop-performance (1.15.0)
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.11.0)
-    standard (1.16.1)
-      rubocop (= 1.35.1)
-      rubocop-performance (= 1.14.3)
+    standard (1.18.0)
+      rubocop (= 1.39.0)
+      rubocop-performance (= 1.15.0)
     stringio (3.0.2)
     unicode-display_width (2.3.0)
     unindent (1.0)

data/README.md

@@ -13,13 +13,16 @@ Install gem and add to application's Gemfile by executing:
 If bundler is not being used to manage dependencies, install the gem by executing:
 
     $ gem install rdoc-markdown
+## Examples
+Find examples in [/examples](/example/) folder. You can regenerate examples by running `./bin/generate.sh`, it will produce examples based on file in `test/data/*` folder.
+
 
 ## Usage
 RDoc will auto-detect rdoc-markdown plugin if it was installed. You just need to instruct RDoc to produce markdown output instead of standard HTML through `format` parameter.
 
 Run following command in directory with ruby source code:
 
-`rdoc --format=markdown`
+`rdoc --format=markdown --markup=markdown`
 
 This will produce a tree of markdown documents and search index in `/doc` folder. Every class in library will have it's own markdown file.
 

data/example/Bird.md

@@ -0,0 +1,17 @@
+# class Bird [](#class-Bird) [](#top)
+The base class for all birds.
+
+ ## Public Instance Methods
+ ### fly(string, number) -> bool [](#method-i-fly)
+ Fly somewhere.
+
+Flying is the most critical feature of birds.
+
+= Example
+
+fly(:south, 70)
+
+ ### speak() { |text| ... } [](#method-i-speak)
+ Produce some noise.
+
+ 

data/example/Duck.md

@@ -0,0 +1,50 @@
+# class Duck [](#class-Duck) [](#top)
+A duck is a [`Waterfowl`](Waterfowl.html) [`Bird`](Bird.html).
+
+Features:
+
+bird::
+
+- speak
+
+- fly
+
+waterfowl::
+
+- swim
+
+ ## Constants
+ | Name | Description |
+ | ---- | ----------- |
+ | **MAX_VELOCITY[](#MAX_VELOCITY)** | Not documented |
+ ## Bird overrides ## Constants
+ | Name | Description |
+ | ---- | ----------- |
+ | **MAX_VELOCITY[](#MAX_VELOCITY)** | Not documented |
+ ## Public Instance Methods
+ ### speak() { |speech| ... } [](#method-i-speak)
+ [`Duck`](Duck.html) overrides generic implementation.
+
+ ## Duck extensions ## Constants
+ | Name | Description |
+ | ---- | ----------- |
+ | **MAX_VELOCITY[](#MAX_VELOCITY)** | Not documented |
+ ## Attributes
+ ### domestic[RW] [](#attribute-i-domestic)
+ True for domestic ducks.
+
+ ### rubber[R] [](#attribute-i-rubber)
+ True for rubber ducks.
+
+ ## Public Class Methods
+ ### new(domestic, rubber) [](#method-c-new)
+ Creates a new duck.
+
+ ### rubber_ducks() [](#method-c-rubber_ducks)
+ Returns list of all rubber ducks.
+
+ ## Public Instance Methods
+ ### useful? -> bool [](#method-i-useful-3F)
+ Checks if this duck is a useful one.
+
+ 

data/example/Object.md

@@ -0,0 +1,8 @@
+# class Object [](#class-Object) [](#top)
+ ## Constants
+ | Name | Description |
+ | ---- | ----------- |
+ | **DEFAULT_DUCK_VELOCITY[](#DEFAULT_DUCK_VELOCITY)** | Default velocity for a flying duck.
+
+ |
+ 

data/example/RDoc/Generator/Markdown.md

@@ -0,0 +1,32 @@
+# class RDoc::Generator::Markdown [](#class-RDoc::Generator::Markdown) [](#top)
+ ## Constants
+ | Name | Description |
+ | ---- | ----------- |
+ | **TEMPLATE_DIR[](#TEMPLATE_DIR)** | Defines a constant for directory where templates could be found
+
+ |
+ ## Attributes
+ ### base_dir[R] [](#attribute-i-base_dir)
+ The path to generate files into, combined with `--op` from the options for a full path.
+
+ ### classes[R] [](#attribute-i-classes)
+ Classes and modules to be used by this generator, not necessarily displayed.
+
+ ### store[R] [](#attribute-i-store)
+ The RDoc::Store that is the source of the generated content
+
+ ## Public Class Methods
+ ### new(store, options) [](#method-c-new)
+ Initializer method for Rdoc::Generator::Markdown
+
+ ## Public Instance Methods
+ ### class_dir() [](#method-i-class_dir)
+ Directory where generated class HTML files live relative to the output dir.
+
+ ### file_dir() [](#method-i-file_dir)
+ this alias is required for rdoc to work
+
+ ### generate() [](#method-i-generate)
+ Generates markdown files and search index file
+
+ 

data/example/RDoc/Generator.md

@@ -0,0 +1,2 @@
+# module RDoc::Generator [](#module-RDoc::Generator) [](#top)
+ 

data/example/RDoc/Markdown.md

@@ -0,0 +1,2 @@
+# class RDoc::Markdown [](#class-RDoc::Markdown) [](#top)
+ 

data/example/RDoc.md

@@ -0,0 +1,2 @@
+# module RDoc [](#module-RDoc) [](#top)
+ 

data/example/Rdoc/Markdown.md

@@ -0,0 +1,6 @@
+# module Rdoc::Markdown [](#module-Rdoc::Markdown) [](#top)
+ ## Constants
+ | Name | Description |
+ | ---- | ----------- |
+ | **VERSION[](#VERSION)** | Not documented |
+ 

data/example/Rdoc.md

@@ -0,0 +1,2 @@
+# module Rdoc [](#module-Rdoc) [](#top)
+ 

data/example/TestGenerator.md

@@ -0,0 +1,10 @@
+# class TestGenerator [](#class-TestGenerator) [](#top)
+ ## Constants
+ | Name | Description |
+ | ---- | ----------- |
+ | **CLASSES[](#CLASSES)** | Not documented |
+ ## Public Instance Methods
+ ### run_generator(file, title) { |options| ... } [](#method-i-run_generator)
+ ### source_file() [](#method-i-source_file)
+ ### test_generator() [](#method-i-test_generator)
+ 

data/example/Waterfowl.md

@@ -0,0 +1,8 @@
+# module Waterfowl [](#module-Waterfowl) [](#top)
+A mixin for waterfowl creatures.
+
+ ## Public Instance Methods
+ ### swim() [](#method-i-swim)
+ Swimming helper.
+
+ 

data/lib/rdoc/generator/markdown.rb

@@ -62,6 +62,8 @@ class RDoc::Generator::Markdown
   # Generates markdown files and search index file
 
   def generate
+    # TODO: Make sure to set --markup parameter to 'markdown'.
+
     debug("Setting things up #{@output_dir}")
 
     setup
@@ -70,7 +72,7 @@ class RDoc::Generator::Markdown
 
     emit_classfiles
 
-    debug("Generate index db file: #{output_dir}/index.db")
+    debug("Generate search index in #{output_dir}/index.db")
 
     emit_sqlite
   end
@@ -149,12 +151,14 @@ class RDoc::Generator::Markdown
 
   def emit_classfiles
     @classes.each do |klass|
-      template = ERB.new File.read(File.join(TEMPLATE_DIR, "classfile.md.erb"))
+      template_content = File.read(File.join(TEMPLATE_DIR, "classfile.md.erb"))
+
+      template = ERB.new template_content, trim_mode: ">"
 
       out_file = Pathname.new("#{output_dir}/#{turn_to_path klass.full_name}")
       out_file.dirname.mkpath
 
-      result = template.result(binding).squeeze.gsub("\n ", "\n").squeeze("\n")
+      result = template.result(binding).squeeze("  ")
 
       File.write(out_file, result)
     end
@@ -171,7 +175,14 @@ class RDoc::Generator::Markdown
   # Converts HTML string into a Markdown string with some cleaning and improvements.
 
   def markdownify(input)
-    md = ReverseMarkdown.convert input
+    # TODO: I should be able to set unknown_tags to "raise" for debugging purposes. Probably through rdoc parameters?
+    # Allowed parameters:
+    # - pass_through - (default) Include the unknown tag completely into the result
+    # - drop - Drop the unknown tag and its content
+    # - bypass - Ignore the unknown tag but try to convert its content
+    # - raise - Raise an error to let you know
+
+    md = ReverseMarkdown.convert input, unknown_tags: :pass_through, github_flavored: true
 
     # unintent multiline strings
     md.unindent!
@@ -182,6 +193,8 @@ class RDoc::Generator::Markdown
 
       "[#{match[1]}](#{match[2]}.md#{match[3]})"
     end
+
+    md.gsub("=== ", "### ").gsub("== ", "## ")
   end
 
   # Aliasing a shorter method name for use in templates

data/lib/rdoc/markdown/version.rb

@@ -2,6 +2,6 @@
 
 module Rdoc
   module Markdown
-    VERSION = "0.3.4"
+    VERSION = "0.3.6"
   end
 end

data/lib/templates/classfile.md.erb

@@ -1,20 +1,20 @@
-# <%= klass.type %> <%= klass.full_name.strip %> [](#<%= klass.aref.strip %>) [](#top)
+# <%= klass.type %> <%= klass.full_name %> [](#<%= klass.aref.strip %>) [](#top)
 <%= h klass.description %>
 <% klass.each_section do |section, constants, attributes| %>
   <% if section.title %>## <%= section.title.strip %> <% end %>
   <% if section.comment %> <%=h  section.description %><% end%>
   <% unless klass.constants.empty? %>
 ## Constants
-    <% klass.constants.each do |const| %>
-### <%= const.name.strip %>[](#<%= const.name.strip %>)
-<% if const.comment %> <%= h const.description %> <%else%> (Not documented) <% end %>
+ | Name | Description |
+ | ---- | ----------- |
+<% klass.constants.each do |const| %> | **<%= const.name %>[](#<%= const.name %>)** | <% unless const.description.empty? %> <%= h const.description %> <%else%> Not documented <% end %> |
     <% end %>
   <% end %>
   <% unless attributes&.empty? %>
 ## Attributes
     <% attributes.each do |attr| %>
 ### <%= attr.name %>[<%= attr.rw %>] [](#<%= attr.aref.strip %>)
-<% if attr.comment %> <%= h attr.description %> <%else%> (Not documented) <% end %>
+<% if attr.comment %> <%= h(attr.description) %> <%else%> Not documented <% end %>
     <% end %>
   <% end %>
   <% klass.methods_by_type(section).each do |type, visibilities| %>
@@ -23,8 +23,8 @@
       <% next if methods.empty? %>
 ##  <%= visibility.capitalize %> <%= type.capitalize %> Methods
       <% methods.each do |method|%>
-### <%= method.name.strip %><%= method.param_seq.strip %> [](#<%= method.aref.strip %>)
-<% if method.comment %> <%= h method.description %>  <% else %> (Not documented) <%end%>
+### <%= method.name %><%= method.param_seq %> [](#<%= method.aref %>)
+<% if method.comment %> <%= h(method.description) %>  <% else %> Not documented <%end%>
       <% end %>
     <% end %>
   <% end %>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.6
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-11-05 00:00:00.000000000 Z
+date: 2022-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -166,6 +166,18 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- example/Bird.md
+- example/Duck.md
+- example/Object.md
+- example/RDoc.md
+- example/RDoc/Generator.md
+- example/RDoc/Generator/Markdown.md
+- example/RDoc/Markdown.md
+- example/Rdoc.md
+- example/Rdoc/Markdown.md
+- example/TestGenerator.md
+- example/Waterfowl.md
+- example/index.db
 - lib/markdown.rb
 - lib/rdoc/discover.rb
 - lib/rdoc/generator/markdown.rb