📖 Add RDoc rake tasks, monkeypatches, styles

Prepended modules are to:
* Fix `:section:` comments
* Convert the "note" list type to tables, like the hanna-nouveau format.
  Unlike hanna-nouveau, label lists remain lists.
* remove redundant "()" from methods

Add basic stylesheet tweaks to give more visual separation between
methods, make the navbar sticky, fix *bold* font-weight, etc.

n.b. some of these styles look best with a couple of rdoc darkfish
patches which have not (yet?) been accepted.

Author: nevans

Gemfile

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 gemspec
 
 gem "rake"
+gem "rdoc"
 gem "test-unit"

docs/styles.css

@@ -0,0 +1,36 @@
+/* this is a work in progress. :) */
+
+main .method-header {
+  background: rgba(27,31,35,0.05);
+  border: 1px solid #6C8C22;
+  padding: 0.5em;
+  border-radius: 4px;
+  /* padding: 0 0.5em; */
+  /* border-width: 0 1px; */
+  /* border-color: #6C8C22; */
+  /* border-style: solid; */
+}
+
+main .method-description, main .aliases {
+  padding-left: 1em;
+}
+
+body {
+  /*
+   * The default (300) can be too low contrast.  Also, many fonts don't
+   * distinguish between 300->400, so <em>...</em> had no effect.
+   */
+  font-weight: 400;
+}
+
+@media only screen and (min-width: 600px) {
+  nav {
+    height: 100%;
+    position: fixed;
+    overflow-y: scroll;
+  }
+
+  nav #class-metadata {
+    margin-bottom: 5em;
+  }
+}

rakelib/rdoc.rake

@@ -0,0 +1,70 @@
+# require "sdoc"
+require "rdoc/task"
+require_relative "../lib/net/imap"
+require 'rdoc/rdoc' unless defined?(RDoc::Markup::ToHtml)
+
+module RDoc::Generator
+  module NetIMAP
+
+    module RemoveRedundantParens
+      def param_seq
+        super.sub(/^\(\)\s*/, "")
+      end
+    end
+
+    # See https://github.com/ruby/rdoc/pull/936
+    module FixSectionComments
+      def markup(text)
+        @store ||= @parent&.store
+        super
+      end
+      def description; markup comment end
+      def comment;     super || @comments&.first end
+      def parse(_comment_location = nil) super() end
+    end
+
+    # render "[label] data" lists as tables.  adapted from "hanna-nouveau" gem.
+    module LabelListTable
+      def list_item_start(list_item, list_type)
+        case list_type
+        when :NOTE
+          %(<tr><td class='label'>#{Array(list_item.label).map{|label| to_html(label)}.join("<br />")}</td><td>)
+        else
+          super
+        end
+      end
+
+      def list_end_for(list_type)
+        case list_type
+        when :NOTE then
+          "</td></tr>"
+        else
+          super
+        end
+      end
+    end
+
+  end
+end
+
+class RDoc::AnyMethod
+  prepend RDoc::Generator::NetIMAP::RemoveRedundantParens
+end
+
+class RDoc::Context::Section
+  prepend RDoc::Generator::NetIMAP::FixSectionComments
+end
+
+class RDoc::Markup::ToHtml
+  LIST_TYPE_TO_HTML[:NOTE] = ['<table class="rdoc-list note-list"><tbody>', '</tbody></table>']
+  prepend RDoc::Generator::NetIMAP::LabelListTable
+end
+
+RDoc::Task.new do |doc|
+  doc.main       = "README.md"
+  doc.title      = "net-imap #{Net::IMAP::VERSION}"
+  doc.rdoc_dir   = "doc"
+  doc.rdoc_files = FileList.new %w[lib/**/*.rb *.rdoc *.md]
+  doc.options << "--template-stylesheets" << "docs/styles.css"
+  # doc.generator  = "hanna"
+end