gem_docs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a07d76db2fbb75383d41735198a4cbf7b1d2b6515653df77e21e8c9575a40ade
+  data.tar.gz: 65e3554324e7c91e8466efba2d032c53d8549e64a7a460cce4ee4d7322fffa40
+SHA512:
+  metadata.gz: 0d9090c6ac05d0d80fb556019bb56c57fbcdd3e1b691e1b38d5b54da8bca5923c00dae9a6e18f616bad189b3c61c981f5d341294c0ccb46e1afde7274569452c
+  data.tar.gz: 86a7c664a77405127a46e03a2233cc20958613965ca6bd3beba2a0ca1ae342192f835a26d22d18ad6f045a6d9f79eb13934942fe0f4baab4a11d17adbc9400dd

data/lib/gem_docs/badge.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module GemDocs
+  module Badge
+    GITHUB_BADGE_RE = %r{actions/workflows.*badge.svg}
+    GITLAB_BADGE_RE = %r{badges/.*pipeline.svg}
+
+    Badge = Struct.new(:name, :marker, :org_block, keyword_init: true)
+
+    def self.ensure!
+      repo = Repo.from_gemspec
+      return false if repo.workflow.to_s.match?(/\A\s*\z/)
+
+      badge = make_badge(repo)
+      ensure_badge!(badge, repo)
+    end
+
+    class << self
+      private
+
+      def make_badge(repo)
+        repo = Repo.from_gemspec
+        org_block =
+          GemDocs.config.badge
+            .gsub('%n', repo.name)
+            .gsub('%h', repo.host)
+            .gsub('%u', repo.user)
+            .gsub('%r', repo.root)
+            .gsub('%b', repo.branch)
+            .gsub('%w', repo.workflow)
+        Badge.new(
+          name:   'GitHub Actions',
+          marker: '#badge',
+          org_block: org_block,
+        )
+      end
+
+      # Write the badge block to the README unless it's already there.  Replace
+      # the #badge marker if present, otherwise add after TITLE.
+      def ensure_badge!(badge, repo)
+        content = File.read(README_ORG)
+        updated =
+          if content.lines.find { |l| l.match?(/\A\s*#{Regexp.quote(badge.marker)}/) }
+            insert_at_marker(badge.marker, content, badge.org_block)
+          elsif (repo.host.include?('github') && content.match?(GITHUB_BADGE_RE)) ||
+                (repo.host.include?('gitlab') && content.match?(GITLAB_BADGE_RE))
+            # Do nothing and return nil to indicate badge present
+            return
+          else
+            insert_after_header(content, badge.org_block)
+          end
+
+        File.write(README_ORG, updated)
+      end
+
+      # Insert the badge block after the org header lines, if any.  If there are
+      # no header lines, insert at the beginning of the file.
+      def insert_after_header(content, block)
+        lines = content.lines
+        out_lines = +''
+
+        in_header = lines.any? { |l| l.match?(/\A\s*\#\+/) }
+        block_added = false
+        lines.each do |line|
+          out_lines <<
+            if in_header && line.match?(/\A\s*\#\+/)
+              line
+            elsif in_header && !line.match?(/\A\s*\#\+/)
+              in_header = false
+              block_added = true
+              if line.match?(/\A\s*\z/)
+                line + block + "\n\n"
+              else
+                "\n" + block + "\n\n" + line
+              end
+            elsif !in_header && !block_added
+              block_added = true
+              block + "\n\n" + line
+            else
+              line
+            end
+        end
+        out_lines
+      end
+
+      def insert_at_marker(marker, content, block)
+        lines = content.lines
+        out_lines = +''
+
+        lines.each do |line|
+          out_lines <<
+            if line.match?(/^#{marker}/)
+              block
+            else
+              line
+            end
+        end
+        out_lines
+      end
+    end
+  end
+end

data/lib/gem_docs/config.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module GemDocs
+  class Config
+    attr_accessor :overview_headings
+    attr_accessor :headers
+    attr_accessor :repo_host
+    attr_accessor :repo_name
+    attr_accessor :repo_user
+    attr_accessor :repo_branch
+    attr_accessor :repo_workflow_dir
+    attr_accessor :repo_workflow_name
+    attr_accessor :badge
+
+    def initialize
+      # Default: support org comment markers
+      @overview_headings = ["Introduction"]
+      @headers =
+        <<~HEADER
+          #+PROPERTY: header-args:ruby :results value :colnames no :hlines yes :exports both :dir "./"
+          #+PROPERTY: header-args:ruby+ :wrap example :session %n_session :eval yes
+          #+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require '%n'"
+          #+PROPERTY: header-args:sh :exports code :eval no
+          #+PROPERTY: header-args:bash :exports code :eval no
+        HEADER
+      @repo_host = nil
+      @repo_name = nil
+      @repo_user = nil
+      @repo_branch = nil
+      @repo_workflow_dir = ".github/workflows"
+      @repo_workflow_name = nil
+      @badge =
+        <<~BADGE
+          #+BEGIN_EXPORT markdown
+          [![CI](https://github.com/%u/%n/actions/workflows/%w/badge.svg?branch=%b)](https://github.com/%u/%n/actions/workflows/%w)
+          #+END_EXPORT
+        BADGE
+    end
+  end
+
+  def self.configure
+    yield(config)
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
+end

data/lib/gem_docs/emacs.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GemDocs
+  module Emacs
+    def self.tangle
+      # ensure_saved
+      expr = <<~ELISP
+        (save-window-excursion
+          (with-current-buffer (find-file-noselect "#{README_ORG}")
+            (save-buffer)
+            (require 'ob-ruby)
+            (org-babel-execute-buffer)
+            (save-buffer)
+            "OK"))
+      ELISP
+
+      if system("emacsclient", "--quiet", "--eval", expr)
+        FileUtils.touch(STAMP)
+      else
+        abort "Babel execution failed"
+      end
+    end
+
+    def self.export
+      # ensure_saved
+      expr = <<~ELISP
+        (save-window-excursion
+          (with-current-buffer (find-file-noselect "#{README_ORG}")
+            (save-buffer)
+            (require 'ox-gfm)
+            (org-gfm-export-to-markdown)))
+      ELISP
+
+      system("emacsclient", "--quiet", "--eval", expr)
+    end
+  end
+end

data/lib/gem_docs/header.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module GemDocs
+  module Header
+    PROPERTY_RE = /^#\+PROPERTY:\s+header-args:ruby/
+
+    # @return String The overview from README per config
+    def self.write_header?
+      return false if present?
+
+      prelim, body = extract_prelim_body
+      new_org = prelim.join.strip + org_headers.strip + "\n\n" + body.join
+      File.write(README_ORG, new_org) > 0
+    end
+
+    def self.present?
+      prelim = extract_prelim_body.first
+      prelim.any? { |h| h.match?(PROPERTY_RE) }
+    end
+
+    class << self
+      private
+
+      # Returns the preliminary comment, blank, and header lines from README.org
+      def extract_prelim_body
+        prelim = []
+        body = []
+        in_prelim = true
+        File.read(README_ORG).lines.each do |line|
+          if in_prelim && line.match?(/^\s*[^#\n]+\s*$/)
+            in_prelim = false
+            body << line
+          elsif in_prelim && (line.match(/^#/) || line.match(/^\s*$/))
+            prelim << line
+          # elsif in_prelim
+          #   in_prelim = false
+          #   body << line
+          else
+            body << line
+          end
+        end
+        [prelim, body]
+      end
+
+      def org_headers
+        repo = Repo.from_gemspec
+        GemDocs.config.headers
+          .gsub('%n', repo.name)
+          .gsub('%h', repo.host)
+          .gsub('%u', repo.user)
+          .gsub('%r', repo.root)
+          .gsub('%b', repo.branch)
+          .gsub('%w', repo.workflow)
+      end
+    end
+  end
+end

data/lib/gem_docs/overview.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'strscan'
+require 'debug'
+
+module GemDocs
+  module Overview
+    BANNER = 'Gem Overview (extracted from README.org by gem_docs)'
+
+    # @return String The overview from README per config
+    def self.write_overview?
+      repo = Repo.from_gemspec
+      target = File.join("lib", "#{repo.name}.rb")
+
+      return false unless File.exist?(target)
+
+      overview = extract
+      return false unless overview
+
+      old_lib = File.read(target)
+      old_match = old_lib.match(overview_re)
+      old_comment = old_match.to_s
+
+      new_comment = <<~RUBY.chomp
+        # #{BANNER}
+        #
+        #{overview.lines.map { |l| l.match?(/\A\s*\z/) ? '#' : "# #{l.rstrip}" }.join("\n")}
+      RUBY
+      return false if old_comment == new_comment
+
+      new_lib =
+        if old_match
+          # There was an overview in the old_lib_content, so replace it with
+          # the new_lib_comment.
+          old_lib.sub(old_comment, new_comment)
+        else
+          scanner = StringScanner.new(old_lib)
+          scanner.scan_until(/^module #{repo.module_name}/)
+          scanner.pre_match + "\n" + new_comment + "\n" + scanner.matched + scanner.rest
+        end
+      File.write(target, new_lib) > 0
+    end
+
+    # Return a Regexp that capture any GemDocs-generated overview comment in
+    # the main module library file.  The Regex requires the comment to come
+    # immediately before the `module <GemName>` line of the libary file, or it
+    # will not match.
+    def self.overview_re
+      heads = GemDocs.config.overview_headings
+      re_str = "#\\s*" + Regexp.quote(BANNER) + ".*"
+      heads.each do |h|
+        re_str << "\\*\\s+#{Regexp.escape(h)}.*"
+      end
+      repo = Repo.from_gemspec
+      re_str += "(?=\\n\\s*module\\s+#{repo.module_name})"
+      Regexp.new(re_str, Regexp::MULTILINE | Regexp::IGNORECASE)
+    end
+
+    def self.present?
+      repo = Repo.from_gemspec
+      target = File.join("lib", "#{repo.name}.rb")
+
+      return false unless File.exist?(target)
+
+      File.read(target).match?(overview_re)
+    end
+
+    class << self
+      private
+
+      # Extract the Overview from the concatenation of all the README.org
+      # top-level sections given in GemDocs.config.overview_headings.
+      def extract
+        text = File.read(README_ORG)
+        heads = GemDocs.config.overview_headings
+        return if heads.nil? || heads.empty?
+
+        result = +''
+        scanner = StringScanner.new(text)
+        heads.each do |h|
+          if scanner.scan_until(/\n(?<head>\s*\*\s+#{Regexp.escape(h)})[^\n]*\n/)
+            this_head = scanner.named_captures['head'] + "\n\n"
+            body_start = scanner.pos
+            body_end =
+              if scanner.scan_until(/\n^\s*\*[^\*\n]+/)
+                scanner.pos - scanner.matched.size
+              else
+                scanner.string.size - 1
+              end
+            scanner.pos = body_end
+            result << this_head + scanner.string[body_start..body_end]
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/gem_docs/repo.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module GemDocs
+  class Repo
+    attr_accessor :root, :host, :user, :name, :module_name
+    attr_accessor :branch, :workflow_dir, :workflow_name
+
+    def initialize(root: nil, host: nil,
+      user: nil,
+      name: nil,
+      module_name: nil,
+      branch: 'master',
+      workflow_dir: nil,
+      workflow_name: nil)
+      @root = root
+      @host = host
+      @user = user
+      @module_name = module_name
+      @name = name
+      @branch = branch
+      @workflow_dir = workflow_dir
+      @workflow_name = workflow_name
+    end
+
+    def workflow
+      workflow_name.to_s
+    end
+
+    class << self
+      def from_gemspec
+        spec = load_gemspec(gemspec_path)
+
+        url =
+          spec.metadata["source_code_uri"] ||
+          spec.metadata["homepage_uri"] ||
+          spec.homepage
+
+        abort "No repository URL found in gemspec metadata" unless url
+
+        # root = File.dirname(File.expand_path(path))
+        root = GemDocs.project_root
+        meta = parse_url(url)
+        name = GemDocs.config.repo_name ||
+               spec.name ||
+               meta[:name] ||
+               File.basename(Dir['*.gemspec'].first) ||
+               File.basename(root)
+        host = GemDocs.config.repo_host ||
+               meta[:host]
+        user = GemDocs.config.repo_user ||
+               meta[:user]
+        mname = to_module(name)
+        branch = GemDocs.config.repo_branch ||
+                 repo_default_branch(root:)
+        wdir, wname = workflow_dir_name
+        new(
+          root: root,
+          host: host,
+          user: user,
+          name: name,
+          module_name: mname,
+          branch: branch,
+          workflow_dir: wdir,
+          workflow_name: wname,
+        )
+      end
+
+      def workflow_dir_name
+        if GemDocs.config.repo_workflow_name && GemDocs.config.repo_workflow_dir
+          workflow_file = File.join(
+            GemDocs.project_root,
+            GemDocs.config.repo_workflow_dir,
+            GemDocs.config.repo_workflow_name,
+          )
+          return [File.dirname(workflow_file), File.dirname(workflow_file)] if File.readable?(workflow_file)
+        end
+
+        dir = File.join(GemDocs.project_root, ".github/workflows")
+        return unless Dir.exist?(dir)
+
+        workflows =
+          Dir.children(dir)
+            .select { |f| f.match?(/\A.+\.ya?ml\z/) }
+            .sort
+        return if workflows.empty?
+
+        fname = workflows.find { |f| f =~ /\A[A-Za-z][^\.]*\.ya?ml\z/i } || workflows.first
+        # File.join(dir, fname)
+        [dir, fname]
+      end
+
+      def to_module(name)
+        name.split(/[-_]/).map(&:capitalize).join('')
+      end
+
+      private
+
+      def repo_default_branch(root:)
+        return "master" unless git_repo?(root:)
+
+        default_branch_from_origin ||
+          fallback_branch ||
+          "master"
+      end
+
+      def fallback_branch
+        return unless git_available?
+
+        branches = %x[git branch --list 2>/dev/null]
+                     .lines
+                     .map { |l| l.sub("*", "").strip }
+
+        return "master" if branches.include?("master")
+        return "main"   if branches.include?("main")
+
+        nil
+      end
+
+      def default_branch_from_origin
+        return unless git_available?
+
+        ref = %x[git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null].strip
+        return if ref.empty?
+
+        ref.split("/").last
+      end
+
+      def git_available?
+        system("git", "--version", out: File::NULL, err: File::NULL)
+      end
+
+      def git_repo?(root: nil)
+        File.directory?(File.join(root, ".git"))
+      end
+
+      # Return {host: <git_host>, user: <user_name>, name: <repo_name> } by parsing the given url
+      def parse_url(url)
+        host_bases = ['github', 'gitlab']
+        md = url.match(%r{(?<host>(?:#{host_bases.join('|')})\.com)/(?<user>[^/]+)/(?<repo_name>[^/]+)(?:\.git)?/?})
+        abort "Unsupported repository URL: #{url}" unless md
+
+        { host: md[:host], user: md[:user], name: md[:repo_name] }
+      end
+
+      def gemspec_path
+        candidates = nil
+        Dir.chdir(GemDocs.project_root) do
+          candidates = Dir["*.gemspec"]
+          abort "No gemspec found" if candidates.empty?
+          abort "Multiple gemspecs found: #{candidates.join(', ')}" if candidates.size > 1
+        end
+        candidates.first
+      end
+
+      def load_gemspec(path)
+        Gem::Specification.load(path) ||
+          abort("Failed to load gemspec: #{path}")
+      end
+    end
+  end
+end

data/lib/gem_docs/skeleton.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module GemDocs
+  module Skeleton
+    PROPERTY_RE = /^#\+PROPERTY:\s+header-args:ruby/
+
+    # @return String The overview from README per config
+    def self.make_readme?
+      return false if present?
+
+      repo = Repo.from_gemspec
+      content = <<~SKEL
+        #+TITLE: #{repo.module_name} Guide
+
+        * Introduction
+
+        * Installation
+
+        #+begin_src sh :eval no
+          bundle add #{repo.name}
+        #+end_src
+
+        If bundler is not being used to manage dependencies, install the gem by executing:
+
+        #+begin_src sh :eval no
+          gem install #{repo.name}
+        #+end_src
+
+        * Usage
+
+        * 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`.
+
+        * Contributing
+        Bug reports and pull requests are welcome on GitHub at
+        https://github.com/#{repo.user}/#{repo.name}.
+
+        * License
+        The gem is available as open source under the terms of the [MIT
+        License](https://opensource.org/licenses/MIT).
+      SKEL
+      File.write(README_ORG, content) > 0
+    end
+
+    def self.present?
+      File.exist?(README_ORG)
+    end
+  end
+end

data/lib/gem_docs/tasks.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module GemDocs
+  extend Rake::DSL
+
+  STAMP = ".tangle-stamp"
+
+  def self.install
+    extend Rake::DSL
+
+    # README.org → README.md when README.org is newer
+    file README_MD => README_ORG do
+      print "Exporting \"#{README_ORG}\" → "
+      GemDocs::Emacs.export
+    end
+
+    # Evaluate code blocks only when README.org changes
+    file STAMP => README_ORG do
+      print "Executing code blocks in #{README_ORG} ... "
+      GemDocs::Emacs.tangle
+      FileUtils.touch(STAMP)
+    end
+
+    namespace :docs do
+      desc "Evaluate code blocks in README.org"
+      task :tangle => [:skeleton, STAMP]
+
+      desc "Export README.org → README.md"
+      task :export => [:badge, README_MD]
+
+      desc "Extract overview from README.org and embed in lib/<gem>.rb for ri/yard"
+      task :overview => [:skeleton, README_ORG] do
+        print "Embedding overview extracted from #{GemDocs::README_ORG} into main gem file ... "
+        if GemDocs::Overview.write_overview?
+          puts "added"
+        else
+          puts "already present"
+        end
+      end
+
+      desc "Create skeleton README.org if one does not exist"
+      task :skeleton do
+        if GemDocs::Skeleton.make_readme?
+          puts "README.org added"
+        else
+          puts "README.org already present"
+        end
+      end
+
+      desc "Insert #+PROPERTY headers at top of README.org for code blocks"
+      task :header => :skeleton do
+        print "Inserting headers ... "
+        if GemDocs::Header.write_header?
+          puts "added"
+        else
+          puts "already present"
+        end
+      end
+
+      desc "Generate YARD HTML documentation"
+      task :yard => [:overview] do
+        puts "Generating YARD documentation ... "
+        GemDocs::Yard.generate
+      end
+
+      desc "Ensure GitHub Actions badge exists in README.org"
+      task :badge => :skeleton do
+        print "Ensuring badges are in README.org ... "
+
+        if GemDocs::Badge.ensure!
+          puts "added"
+        else
+          puts "already present"
+        end
+      end
+
+      desc "Run all documentation tasks (examples, readme, overview, yard, ri)"
+      task :all => [:skeleton, :header, :tangle, :export, :overview, :yard]
+    end
+  end
+end

data/lib/gem_docs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GemDocs
+  VERSION = "0.1.0"
+end

data/lib/gem_docs/yard.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GemDocs
+  module Yard
+    # Generate HTML documentation via YARD
+    def self.generate(supress_out: false)
+      write_yardopts
+      Dir.chdir(GemDocs.project_root) do
+        redirect = supress_out ? '>/dev/null 2>&1' : ''
+        unless system("yard doc --no-private #{redirect}")
+          abort "Failed to generate YARD documentation"
+        end
+      end
+    end
+
+    class << self
+      private
+
+      # Path to the .yardopts file in the project root
+      def yardopts_path
+        File.expand_path(".yardopts", GemDocs.project_root)
+      end
+
+      # Contents of .yardopts
+      def yardopts_contents
+        <<~YOPTS
+          --markup markdown
+          --output-dir doc
+          --readme README.md
+          lib/**/*.rb
+        YOPTS
+      end
+
+      # Write .yardopts only if needed
+      def write_yardopts
+        if !File.exist?(yardopts_path) || File.read(yardopts_path) != yardopts_contents
+          File.write(yardopts_path, yardopts_contents)
+        end
+      end
+    end
+  end
+end

data/lib/gem_docs.rb

@@ -0,0 +1,264 @@
+# -*- mode: ruby -*-
+# frozen_string_literal: true
+
+# Gem Overview (auto-generated by gem_docs)
+#
+# * Usage
+
+require "rake"
+require "rake/dsl_definition"
+require "fileutils"
+
+# Gem Overview (extracted from README.org by gem_docs)
+#
+#
+#
+# * Overview
+#
+# One of the more onerous tasks when writing a ~gem~ or other ~github~ project
+# is maintaining the documentation, and keeping it consistent and up-to-date.
+# One of the better options for writing the ~README~ file that gets displayed by
+# ~github~ as the main documentation is to write the file in ~org-mode~,
+# ~README.org~ the export it to markdown ~README.md~ for display by ~github~.
+#
+# Doing so gives you access to ~org-mode~'s code blocks for writing example code
+# to demonstrate the ~gem~ or other documents being presented.  If you do so,
+# ~github~ will render your ~README.org~ file in ~HTML~ and give you a credible
+# result.  However, ~github~ cannot handle some ~org-mode~ features, and in
+# particular, it will not render ~#+RESULTS~ blocks showing the results of code
+# block execution unless you wrap the results in something like a
+# ~#+begin_example~ block and manually delete the ~#+RESULTS~ markers.
+# Exporting to markdown eliminates that hassle.
+#
+# This gem contains ~rake~ tasks to facilitate the production of documentation
+# in other gems.
+#
+# It provides tasks for:
+#
+# - ensuring that proper code block setup is included in ~README.org~ to
+#   facilitate running ~ruby~ code blocks in a session using the current version
+#   of the library,
+# - running the code block examples in a ~README.org~ by invoking ~emacsclient~,
+# - exporting ~README.org~ to Git-flavored markdown in ~README.md~
+# - ensuring a workflow or ci badge is present in the ~README.md~
+# - generating yard documents for your repo, and
+# - copying the introductory contents of the README as a leading comment in your
+#   main gem library file so it gets picked up as an overview for ~ri~ and ~yri~
+#
+# * Usage
+#
+# ** Create a skeleton README.org file
+# This is a simple task that creates a bare-bones ~README.org~ file to get
+# started with.  It does create the file with the name of the gem and other repo
+# detains filled in.  If there is already a README.org file, it does nothing.
+#
+# #+begin_src ruby :eval no
+#  rake docs:skeleton
+# #+end_src
+#
+# ** Add proper ~#+PROPERTY~ headers in ~README.org~: ~rake docs:headers~
+# **
+# Getting emacs code blocks to render well in your ~README.org~ takes proper
+# configuration of the code block headers in Emacs.
+#
+# #+begin_src ruby :eval no
+#  rake docs:headers
+# #+end_src
+#
+# By default, the ~gem_docs~ ~rake docs:headers~ task will add the following
+# headers to the top of your ~README.org~ file.  It does nothing if any ruby
+# header args are already present, so remove them if you want these installed.
+#
+# #+begin_example
+# #+PROPERTY: header-args:ruby :results value :colnames no :hlines yes :exports both :dir "./"
+# #+PROPERTY: header-args:ruby+ :wrap example :session gem_docs_session
+# #+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require '%n'"
+# #+PROPERTY: header-args:sh :exports code :eval no
+# #+PROPERTY: header-args:bash :exports code :eval no
+# #+end_example
+#
+# Here's what the ruby headers buy you:
+# - ~:results value~ :: the value of the last expression in the block is rendered
+#   as the results of code execution.  If you want the output instead for a
+#   particular block, just add the block argument ~:results output~ to the code
+#   block.
+# - ~:colnames no~ :: prevents org from processing the column headers in tables
+#   it renders.  It is better for you to control column headers, and this
+#   setting allows this.
+# - ~:hlines yes~ :: prevents org from stripping hlines from tables, which also
+#   allows you to control the insertion of hlines in tables.
+# - ~:exports both~ :: causes both your code and the results of evaluation to be
+#   exported to the ~README.md~.  Your example blocks should demonstrate the use
+#   of the gem, and the reader will want to see both the code and its results.
+# - ~:dir "./"~ :: causes each code block to execute with your gem's root
+#   directory as its current directory.
+# - ~:wrap example~ :: this wraps the result of code block evaluation in
+#   ~#+begin_example~ / ~#+end_example~ so that the results are displayed
+#   literally.
+# - ~:session gem_docs_session~ :: causes the code blocks to execute in a
+#   continuous session, so that variables set up in one code block are
+#   accessible in later code blocks.  Without this, you would have to build the
+#   code environment anew with each code block which obscures the readability of
+#   your ~README~.  The session name is set to '<gem_name>_session'
+#   automatically, where <gem_name> is the name of your gem.
+# - ~:prologue "$:.unshift('./lib') unless $:.first == './lib'; require 'gem_name'"~
+#   :: this prologue gets executed before each code block execution and ensures
+#   that the version of the gem library is you current development version;
+#   otherwise, your code blocks could be running a version from a prior
+#   installation of the gem.  The 'gem_name' in the require is set to the name
+#   of your gem automatically.
+#
+# The ~docs:headers~ task also turns off evaluation of shell code blocks since
+# these will often be such things as demonstrating the shell commands to install
+# the gem, etc.  Of course, you can override this for particular code blocks.
+#
+# Those headers are in fact what I am using in this ~README~, and here is how
+# they work:
+#
+# #+begin_src ruby
+#   result = []
+#   result << ['N', 'exp(N)']
+#   result << nil
+#   0.upto(10) do |n|
+#     result << [n/3.0, Math.exp(n/3.0)]
+#   end
+#   result
+# #+end_src
+#
+# #+RESULTS:
+# #+begin_example
+# |                  N |             exp(N) |
+# |--------------------+--------------------|
+# |                0.0 |                1.0 |
+# | 0.3333333333333333 | 1.3956124250860895 |
+# | 0.6666666666666666 | 1.9477340410546757 |
+# |                1.0 |  2.718281828459045 |
+# | 1.3333333333333333 | 3.7936678946831774 |
+# | 1.6666666666666667 |   5.29449005047003 |
+# |                2.0 |   7.38905609893065 |
+# | 2.3333333333333335 | 10.312258501325767 |
+# | 2.6666666666666665 | 14.391916095149892 |
+# |                3.0 | 20.085536923187668 |
+# | 3.3333333333333335 |  28.03162489452614 |
+# #+end_example
+#
+# I built the table in the output by returning an array of arrays, which
+# org-mode renders as a table in the output.  Notice that I added an hline to
+# the output by simply adding ~nil~ to the outer array where I wanted the hline
+# to occur.
+#
+# Apart from all the convenient markup that ~org-mode~ allows, the ability to
+# easily demonstrate your gem's code in this way is the real killer feature of
+# writing your ~README~ in ~org-mode~ then exporting to markdown.
+#
+# ** Run the Code Blocks in README.org: ~rake docs:tangle~
+# You can invoke ~emacsclient~ to run all the example code blocks in your
+# ~README.org~ that are set for evaluation:
+#
+# Note that the ~tangle~ task relies on ~emacsclient~ to evaluate the code blocks in
+# ~README.org~, so your Emacs ~init~ files should start [[info:emacs#Emacs Server][the Emacs server]] in
+# order to work properly.
+#
+# I use the following snippet in my Emacs init file:
+#
+# #+begin_src emacs-lisp :eval no
+#   (require 'server)
+#   (unless (server-running-p)
+#     (message "Starting Emacs server")
+#     (server-start))
+# #+end_src
+#
+# Then, you can evaluate all the code blocks in your ~README.org~ like this:
+#
+# #+begin_src ruby :eval no
+#  rake docs:tangle
+# #+end_src
+#
+# ** Ensure that a Badge is Present in ~README.md~: ~rake docs:badge~
+# It is reassuring to consumers of your gem that your gem passes its workflow
+# tests on github.  This task checks to see if a "badge" indicating success or
+# failure is present and, if not, inserts one at the top of the ~README.org~
+# such that it will get exported to ~README.md~ when =rake docs:export= is run.
+#
+# If you want to place the badge somewhere else in you ~README.org~, place the
+# special comment ~#badge~ where you want the badge located and the task will
+# place it there.
+#
+# If there is already a badge present, the task will not modify the ~README.org~
+# file.
+#
+# ** Export ~README.org~ to ~README.md~: ~rake docs:export~
+# You can write the ~README~ in Emacs org-mode, using all its features
+# including the execution of code blocks, and then export to git-flavored
+# markdown.
+#
+# If your repo contains both ~README.org~ and ~README.md~, github (and gitlab)
+# will render the markdown version.
+#
+# Github renders markdown better than it renders org files, so this helps with
+# the readability of the ~README~ on github.  For example, if you write the
+# ~README~ in org mode without exporting to markdown, ~github~ will not render
+# the ~#+RESULTS~ blocks unless you manually delete the ~#+RESULTS~ tag from the
+# output.  This is tedious and error-prone, so it is best that you write the
+# ~README~ in ~org-mode~ and export to ~markdown~.  That's what this task
+# enables.
+#
+# Also note that when ~github~ renders your ~README.md~, it automatically adds a
+# table of contents, so putting one in the ~README.org~ file is redundant.  If
+# you want to have one for your own purposes, just set the ~:noexport~ tag on it
+# so it doesn't get put into the ~README.md~
+#
+# #+begin_src ruby :eval no
+#   rake docs:export
+# #+end_src
+#
+# ** Generate Yard Documents: ~rake docs:yard~
+# This task generates a suitable ~.yardopts~ file if none exists and then
+# generates ~yard~ documents into the gem's ~doc~ directory.  It also makes sure
+# that ~yard~ knows about your ~README.md~ file so user's of your gem will be
+# able to get an overview of how to use your gem.
+#
+# #+begin_src ruby :eval no
+#   rake docs:yard
+# #+end_src
+#
+# ** Generate an Overview Comment for the Main gem File: ~rake docs:overview~
+# Gem's typically gather into a central library file all the require's and other
+# setup needed for the gem and the file is given the same name as the gem.  For
+# example, this gem uses the file =lib/gem_docs.rb= for this purpose.  Since
+# this =lib= directory is placed in the user's =LOADPATH=, a =require
+# 'gem_docs'= or =require '<gemname>'= effectively initializes the gem.
+#
+# By convention the comment immediately above the 'module' definition in your
+# main library file is used by =yard= and =ri= as the overview for the gem.
+#
+# #+begin_src ruby :eval no
+#   rake docs:overview
+# #+end_src
+#
+# This extracts the "Introduction" section from ~README.org~ and makes it the
+# overview comment in the gem's main library file.  If it already exists, it
+# replaces it with any newer version of the "Introduction" section, otherwise,
+# it does not change the file.
+module GemDocs
+  require_relative "gem_docs/version"
+  require_relative "gem_docs/config"
+  require_relative "gem_docs/repo"
+  require_relative "gem_docs/emacs"
+  require_relative "gem_docs/overview"
+  require_relative "gem_docs/yard"
+  require_relative "gem_docs/badge"
+  require_relative "gem_docs/header"
+  require_relative "gem_docs/skeleton"
+  require_relative "gem_docs/tasks"
+
+  README_ORG = "README.org"
+  README_MD = "README.md"
+
+  # Auto-detect project root (handles being run from subdirs)
+  def self.project_root
+    here = Dir.pwd
+    here = File.dirname(here) until !Dir['*.gemspec', 'Gemfile'].empty? || here == "/"
+    here
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: gem_docs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel E. Doherty
+bindir: bin
+cert_chain: []
+date: 2025-12-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Shared tasks for README.org execution, GFM export, YARD integration (future),
+  etc.
+email:
+- ded@ddoherty.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/gem_docs.rb
+- lib/gem_docs/badge.rb
+- lib/gem_docs/config.rb
+- lib/gem_docs/emacs.rb
+- lib/gem_docs/header.rb
+- lib/gem_docs/overview.rb
+- lib/gem_docs/repo.rb
+- lib/gem_docs/skeleton.rb
+- lib/gem_docs/tasks.rb
+- lib/gem_docs/version.rb
+- lib/gem_docs/yard.rb
+homepage: https://github.com/ddoherty03/gem_docs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ddoherty03/gem_docs
+  source_code_uri: https://github.com/ddoherty03/gem_docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Documentation automation for Ruby gems
+test_files: []