rdoc-markdown 0.1.14 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12c1ba51ac28269b904c171a33ced989e93a6ec55cdeb5b07cf1267bb73f288e
-  data.tar.gz: 816fce30041fc92080f14dfe722e27261b9bc65fbec97b00a9646962a6daa0b6
+  metadata.gz: 16494339df3b522fae317e9010c0a9ee8cae1a7f4452595c8fde01e238421c64
+  data.tar.gz: 1dec9b05ccdea281811213800b2301a4f89097dcaacbf72ac59fa7c85aeff676
 SHA512:
-  metadata.gz: 47cae1695d164805c74056118cc2048594281e304fd73952a6e8a0602a89f360beae06f5a6cd01929bfb6b1d094716b59a68a748a9409f4544bb18df2cf8c6d5
-  data.tar.gz: 544b83ef2a0f8dbccc7fbba8ef046f5fccd160ea0f030f6dba237ee6d061e4a13cae0c04fbd701d650993ec1d966f202ce948330101c9077d160bfdf4ef9c089
+  metadata.gz: 30b4a879efd549f01f627558c390b34b05aece87ce14fe46293770e342c90fdaf176457b50fad52f215de6aa91b7477607601530d8874f60869570e9990b043d
+  data.tar.gz: 76947d62302a58b3ceeb41d78be86dcbe7d6032fa41579e9287567aecda5bf23c7271bfb453c8125d9dd6d6b934bd5de996637145a2ba377f068f8198909c82a

data/Gemfile.lock

@@ -1,12 +1,13 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.1.13)
+    rdoc-markdown (0.2.1)
       activesupport (~> 7.0)
       erb (~> 2.0)
       extralite-bundle (~> 1.0)
       rdoc (~> 6.0)
       reverse_markdown (~> 2.0)
+      unindent (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -55,7 +56,7 @@ GEM
       rubocop-ast (>= 1.20.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.22.0)
+    rubocop-ast (1.23.0)
       parser (>= 3.1.1.0)
     rubocop-performance (1.14.3)
       rubocop (>= 1.7.0, < 2.0)
@@ -68,6 +69,7 @@ GEM
     tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.3.0)
+    unindent (1.0)
 
 PLATFORMS
   arm64-darwin-21

data/README.md

@@ -1,7 +1,5 @@
 # Rdoc::Markdown
-This gem is focused on spitting readable markdown files based on rdoc documentation. It should also come with sqlite database as an index (but this is so far only in plans). 
-
-It is still actively in development and while works as proof of concept, still has some quirks here and there.
+Rdoc Generator plugin to generate markdown documentation and search index as sqlite database that goes along with it.
 
 ## Installation
 
@@ -14,15 +12,10 @@ If bundler is not being used to manage dependencies, install the gem by executin
     $ gem install rdoc-markdown
 
 ## Usage
-First thing to do, is to install a gem
-
-`gem install rdoc-markdown`
-
-Then proceed to directory where you want to generate documentation:
 
 `rdoc --format=markdown`
 
-Don't forget to append `--debug` to have a bit more information in case thing fail (and they will probably do, because this entire thing is experimental).
+No additional parameters are currently available, but that may change.
 
 ## Development
 Biggest issue is testing this locally, but that's not as hard to do these days.
@@ -41,11 +34,23 @@ or you can do the same, but through gemfile:
 gem 'rdoc-markdown`, path: "../rdoc-markdown/`
 ```
 
+I have scripted entire process in [rm-reload.sh script](https://github.com/skatkov/gum/blob/master/rm-reload.sh). But it assumes, that you have [gum library](https://github.com/charmbracelet/gum) installed.
+
+## Testing
+Testing is not excessive, just verifies that basic functionality is operational. Following command should run entire testsuit:
+
+```
+rake test
+```
+
 ## Release
 ```
 gem build rdoc-markdown.gemspec
 gem push rdoc-markdown-0.1.2.gem
 ```
+
+There is `./publish.sh` script that does that. But it assumes, that you have [gum library](https://github.com/charmbracelet/gum) installed.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/skatkov/rdoc-markdown. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/skatkov/rdoc-markdown/blob/master/CODE_OF_CONDUCT.md).

data/lib/rdoc/generator/markdown.rb

@@ -7,10 +7,14 @@ require "erb"
 require "reverse_markdown"
 require 'extralite'
 require 'active_support/core_ext/string/inflections'
+require 'unindent'
 
 class RDoc::Generator::Markdown
   RDoc::RDoc.add_generator self
 
+  ##
+  # Defines a constant for directory where templates could be found
+
   TEMPLATE_DIR = File.expand_path(
     File.join(File.dirname(__FILE__), "..", "..", "templates")
   )
@@ -28,7 +32,7 @@ class RDoc::Generator::Markdown
 
   ##
   # Classes and modules to be used by this generator, not necessarily
-  # displayed.  See also #modsort
+  # displayed.
 
   attr_reader :classes
 
@@ -43,6 +47,9 @@ class RDoc::Generator::Markdown
   # this alias is required for rdoc to work
   alias_method :file_dir, :class_dir
 
+  ##
+  # Initializer method for Rdoc::Generator::Markdown
+
   def initialize(store, options)
     @store = store
     @options = options
@@ -52,12 +59,13 @@ class RDoc::Generator::Markdown
     @classes = nil
   end
 
-  def generate
-    setup
+  ##
+  # Generates markdown files and search index file
 
-    debug("Create directory #{@output_dir}")
+  def generate
+    debug("Setting things up #{@output_dir}")
 
-    output_dir.mkpath
+    setup
 
     debug("Generate documentation in #{@output_dir}")
 
@@ -73,6 +81,9 @@ class RDoc::Generator::Markdown
   attr_reader :options
   attr_reader :output_dir
 
+  ##
+  # This method is used to output debugging information in case rdoc is run with --debug parameter
+
   def debug(str = nil)
     if $DEBUG_RDOC
       puts "[rdoc-markdown] #{str}" if str
@@ -80,8 +91,12 @@ class RDoc::Generator::Markdown
     end
   end
 
-  def emit_sqlite
-    db = Extralite::Database.new("#{output_dir}/index.db")
+  ##
+  # This class emits a search index for generated documentation as sqlite database
+  #
+
+  def emit_sqlite(name="index.db")
+    db = Extralite::Database.new("#{output_dir}/#{name}")
 
     db.execute <<-SQL
       create table contentIndex (
@@ -107,7 +122,7 @@ class RDoc::Generator::Markdown
         result << {
           name: "#{klass.full_name}.#{method.name}",
           type: "Method",
-          path: "#{turn_to_path(klass.full_name)}#meth-#{ActiveSupport::Inflector.parameterize method.name}"
+          path: "#{turn_to_path(klass.full_name)}##{method.aref}"
         }
       end
 
@@ -115,7 +130,7 @@ class RDoc::Generator::Markdown
         result << {
           name: "#{klass.full_name}.#{const.name}",
           type: "Constant",
-          path: "#{turn_to_path(klass.full_name)}#const-#{ActiveSupport::Inflector.parameterize const.name}"
+          path: "#{turn_to_path(klass.full_name)}##{ActiveSupport::Inflector.parameterize const.name}"
         }
       end
 
@@ -123,7 +138,7 @@ class RDoc::Generator::Markdown
         result << {
           name: "#{klass.full_name}.#{attr.name}",
           type: "Attribute",
-          path: "#{turn_to_path(klass.full_name)}#attr-#{ActiveSupport::Inflector.parameterize attr.name}"
+          path: "#{turn_to_path(klass.full_name)}##{attr.aref}"
         }
       end
     end
@@ -159,16 +174,22 @@ class RDoc::Generator::Markdown
     end
   end
 
-
-  private
+  ##
+  # Takes a class name and converts it into a Pathname
 
   def turn_to_path(class_name)
     "#{class_name.gsub("::", "/")}.md"
   end
 
+  ##
+  # Converts HTML string into a Markdown string with some cleaning and improvements.
+
   def markdownify(input)
     md= ReverseMarkdown.convert input, github_flavored: true
 
+    # unintent multiline strings
+    md.unindent!
+
     # Replace .html to .md extension in all markdown links
     md = md.gsub(/\[(.+)\]\((.+).html(.*)\)/) do |_|
       match = Regexp.last_match
@@ -181,17 +202,22 @@ class RDoc::Generator::Markdown
     md.gsub("[↑](#top)", "").lstrip
   end
 
+  # Aliasing a shorter method name for use in templates
   alias_method  :h, :markdownify
 
+  ##
+  # Prepares for document generation, by creating required folders and initializing variables.
+  # Could be called multiple times.
+
   def setup
     return if instance_variable_defined?(:@output_dir)
 
     @output_dir = Pathname.new(@options.op_dir).expand_path(@base_dir)
+    @output_dir.mkpath
 
     return unless @store
 
     @classes = @store.all_classes_and_modules.sort
-    @modsort = get_sorted_module_list @classes
   end
 
   ##

data/lib/rdoc/markdown/version.rb

@@ -2,6 +2,6 @@
 
 module Rdoc
   module Markdown
-    VERSION = "0.1.14"
+    VERSION = "0.2.1"
   end
 end

data/lib/templates/classfile.md.erb

@@ -1,24 +1,23 @@
 # <% if klass.type == 'class' %><%= klass.type.capitalize %>: **<%= klass.full_name %>**<% if klass.superclass %> < <% end %><% unless String === klass.superclass %><%= klass.superclass&.name %> <% else %> <%= klass.superclass %> <% end %> <% else %> <%= klass.type.capitalize %>: <%= klass&.name %> <% end %>
-<% if klass.description && !klass.description.empty? %><%= h klass.description %><% end %>
+<%= h klass.description %>
 <% unless klass.constants.empty? %>
-## Constants
-***
-<% klass.constants.sort_by { |x| x.name }.each do |const| %> **<%= const.name %>**
-  <%= h const.description %>
+| Constants | Description |
+| ------------- | ------------- |
+<% klass.constants.sort_by { |x| x.name }.each do |const| %> |**[<%= const.name %>](#<%= ActiveSupport::Inflector.parameterize const.name%>)** | <%= h const.description %> |
 <% end %><% end %>
 <% unless klass.attributes.empty? %>
 ## Attributes
 <% klass.attributes.sort_by { |x| x.name }.each do |attr| %>
-  **[<%= attr.rw %>]** <%= attr.name %>
+  [[**<%= attr.rw %>**] <%= attr.name %>](#<%= attr.aref %>)
 <% end %><% end %>
 <% unless klass_methods.empty? %>
 ## Public Class Methods
 ***
-<% klass_methods.each do |method| %>### <%= method.name %><%= method.params %>
+<% klass_methods.each do |method| %>### [<%= method.name %><%= method.params %>](#<%= method.aref %>)
 
 <%= h method.description %><% end %><% end %>
 <% unless instance_methods.empty? %>
 ## Public Instance Methods
-<% instance_methods.each do |method| %>### <%= method.name %><%= method.params %>
+<% instance_methods.each do |method| %>### [<%= method.name %><%= method.params %>](#<%= method.aref %>)
 
 <%= h method.description %><% end %><% end %>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.2.1
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-20 00:00:00.000000000 Z
+date: 2022-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: unindent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -150,8 +164,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: rdoc generator that produces markdown files and sqlite database with
-  index of all file
+description: RDoc plugin to generate markdown documentation and search index as sqlite
+  database for entire content.
 email:
 - github@skatkov.com
 executables: []
@@ -202,5 +216,5 @@ requirements: []
 rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
-summary: rdoc generator that produces markdown files
+summary: RDoc plugin to generate markdown documentation
 test_files: []