gem_docs 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eadd7f7e5421dca33c5297a35fd54283a002b6f87757796aaa697e5ba39ce50
-  data.tar.gz: 3dd763c1846d02c694a0c9aa85a56e59cae9be90a661778dc94a0ab95a5ba971
+  metadata.gz: 23f41751e4958ef349292a6620097b7319493abce0ee282d7a0bf8d7aa064195
+  data.tar.gz: 944ffcfa8220c6991ff91282b61bf5926027d47da432c2087aec34be1a2c40ab
 SHA512:
-  metadata.gz: e18a7cdf17f776fca792566409e1b9d5f9ab1119e20980d7d204f116204461dd6e335b5bcb79ad5ba5d05abc6594780517e76fe4f86458d8b15c1fd0a8d1df0f
-  data.tar.gz: baef0a42000b8f28f8721e3502b694669a8a1c335f5a82f2bd45344e10494bfffe792e93e83bcfba8470fdad1ab533b0b1ada895def53ec4a1b3a0c088f64cf7
+  metadata.gz: 5666427b3018cbb1f6a923e211cbdae7a6b7c86d63e264fca9d24672e005f65f7565716c4a8cd1746d1c52b7a8f46cbaba11b4cfa1df61f1e073888c8ec05c76
+  data.tar.gz: 8924cc0a2db42fe04cf7ce40837803aa768a9814a45a8db498fe790eeb1ca3ab15180c316669adfc71c9d2f3ed950bf1812a55dc2ee6e3b6e9f649f82fe63303

data/lib/gem_docs/config.rb

@@ -11,15 +11,18 @@ module GemDocs
     attr_accessor :repo_workflow_dir
     attr_accessor :repo_workflow_name
     attr_accessor :badge
+    attr_accessor :emacs_timeout
 
     def initialize
+      @emacs_timeout = 120
       # 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:ruby+ :wrap example :session %n_session :eval never-export
+          #+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require '%n'; nil"
+          #+PROPERTY: header-args:ruby+ :ruby "bundle exec irb"
           #+PROPERTY: header-args:sh :exports code :eval no
           #+PROPERTY: header-args:bash :exports code :eval no
         HEADER

data/lib/gem_docs/doctor.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module GemDocs
+  # Advisory static checks; never evaluates examples or starts Emacs.
+  class Doctor
+    def self.run
+      new.run
+    end
+
+    def initialize
+      @root = GemDocs.project_root
+      @suggestions = []
+    end
+
+    def run
+      readme = path(README_ORG)
+      if File.file?(readme)
+        text = File.read(readme)
+        outline, ruby_blocks = scan_org(text)
+        check_overview(outline)
+        check_headers(outline) unless ruby_blocks.empty?
+        check_version(outline)
+        check_export(readme)
+      else
+        suggest(README_ORG, "File is missing. Run bundle exec rake docs:skeleton:readme to create it.")
+        check_export(readme) if File.file?(path(README_MD))
+      end
+      check_yard
+      puts "GemDocs doctor: #{@root}"
+      puts "Advisory static checks; Org's inherited and per-block settings may intentionally differ."
+      if @suggestions.empty?
+        puts "No suggestions from these checks."
+      else
+        @suggestions.each { |message| puts "- #{message}" }
+      end
+      @suggestions
+    end
+
+    private
+
+    def path(name)
+      File.join(@root, name)
+    end
+
+    def suggest(file, message)
+      @suggestions << "#{file}: #{message}"
+    end
+
+    # Exclude examples and export blocks so quoted headers/headings do not
+    # masquerade as document configuration.
+    def scan_org(text)
+      outline = +''
+      ruby_blocks = []
+      block = nil
+      text.each_line do |line|
+        if block
+          block = nil if line.match?(/^\s*#\+end_#{Regexp.escape(block)}\b/i)
+        elsif (match = line.match(/^\s*#\+begin_(\w+)\b(.*)/i))
+          block = match[1]
+          ruby_blocks << line if block.casecmp?('src') && match[2].match?(/^\s+ruby\b/i)
+        else
+          outline << line
+        end
+      end
+      [outline, ruby_blocks]
+    end
+
+    def check_overview(outline)
+      heads = Array(GemDocs.config.overview_headings)
+      return if heads.empty?
+
+      sections = outline.scan(/^\* +([^\n]+)\n(.*?)(?=^\* |\z)/m).to_h
+      missing = heads.reject { |head| sections.key?(head) }
+      unless missing.empty?
+        suggest(README_ORG, "No top-level overview section for #{missing.map(&:inspect).join(', ')}. " \
+          "Add prose under that heading, or set c.overview_headings to existing top-level headings " \
+          "(for example, ['Overview']) in GemDocs.configure.")
+      end
+      (heads - missing).each do |head|
+        next unless sections[head].strip.empty?
+
+        suggest(README_ORG, "The #{head.inspect} overview section is empty. Add a short description for YARD/ri.")
+      end
+    end
+
+    def check_headers(outline)
+      headers = outline.lines.grep(/^#\+PROPERTY:\s+header-args:ruby\+?\s/i).join
+      if headers.empty?
+        suggest(README_ORG, "Ruby examples have no file-level Ruby headers. Run bundle exec rake docs:headers " \
+          "or review local/inherited settings before adding the defaults.")
+        return
+      end
+      unless headers.match?(/:eval\s+never-export\b/)
+        suggest(README_ORG, "Ruby headers do not specify :eval never-export. Consider it to execute examples with " \
+          "docs:tangle and reuse results during export; docs:all then runs examples once.")
+      end
+      if headers.match?(/:eval\s+yes\b/)
+        suggest(README_ORG, "Ruby headers contain :eval yes, which allows execution during export. " \
+          "Remove or replace conflicting :eval settings if adopting never-export.")
+      end
+      unless headers.match?(/:session\s+(?!none\b)\S+/)
+        suggest(README_ORG, "No shared Ruby :session is declared. Add one if examples depend on earlier variables.")
+      end
+      unless headers.match?(/:exports\s+both\b/)
+        suggest(README_ORG, "Consider :exports both for Ruby examples so exported docs show code and saved results.")
+      end
+      unless headers.match?(/:wrap\s+example\b/)
+        suggest(
+          README_ORG,
+          "Consider :wrap example to preserve saved Ruby output as literal text during Markdown export.",
+        )
+      end
+      unless headers.match?(/:prologue\b/)
+        suggest(README_ORG, "No Ruby :prologue is declared. Ensure examples load the local gem before using it.")
+      end
+    end
+
+    def check_version(outline)
+      blocks = outline.scan(Skeleton::VERSION_BLOCK_RE)
+      if blocks.size != 1
+        suggest(README_ORG, "Expected one managed README version block, found #{blocks.size}. " \
+          "Remove duplicates if needed, then run bundle exec rake docs:skeleton:readme.")
+        return
+      end
+      specs = Dir.glob(path('*.gemspec'))
+      return unless specs.one?
+
+      spec = Gem::Specification.load(specs.first)
+      return unless spec
+      return if blocks.first.lines.any? { |line| line.strip == "Version: #{spec.version}" }
+
+      suggest(
+        README_ORG,
+        "README version differs from gemspec #{spec.version}. Run bundle exec rake docs:skeleton:readme.",
+      )
+    end
+
+    def check_export(readme)
+      markdown = path(README_MD)
+      if !File.file?(markdown)
+        suggest(README_MD, "File is missing. Run bundle exec rake docs:export after refreshing example results.")
+      elsif File.open(markdown, &:gets).to_s.chomp != Emacs::README_MARKER
+        suggest(README_MD, "Protected from export: missing first-line #{Emacs::README_MARKER}. " \
+          "Keep handwritten Markdown as-is; review/back up older generated files before adding the marker to opt in.")
+      elsif File.file?(readme) && File.mtime(readme) > File.mtime(markdown)
+        suggest(README_MD, "README.org is newer; export may be stale. " \
+          "Run docs:all after example edits, or docs:export if saved results are current.")
+      end
+    end
+
+    def check_yard
+      unless File.file?(path('.yardopts'))
+        suggest(".yardopts", "File is missing. docs:yard creates defaults; review and commit that configuration.")
+      end
+      %w[.yardoc doc].each do |name|
+        next unless File.directory?(path(name))
+
+        tracked, status = Open3.capture2('git', '-C', @root, 'ls-files', '--', name, err: File::NULL)
+        next unless status.success?
+
+        if !tracked.empty?
+          suggest("#{name}/", "Contains tracked generated YARD files. Consider untracking and ignoring that directory.")
+        else
+          _, ignored = Open3.capture2('git', '-C', @root, 'check-ignore', '-q', '--', "#{name}/", err: File::NULL)
+          suggest(".gitignore", "Add /#{name}/ to exclude generated YARD output.") unless ignored.success?
+        end
+      rescue Errno::ENOENT
+        # Git is optional; the remaining static checks still apply.
+        next
+      end
+    end
+  end
+end

data/lib/gem_docs/emacs.rb

@@ -1,39 +1,149 @@
 # frozen_string_literal: true
 
+require 'tempfile'
+
 module GemDocs
   module Emacs
+    class Error < StandardError; end
+    README_MARKER = '<!-- Generated by gem_docs -->'
+
     def self.tangle
+      path = File.expand_path(README_ORG, GemDocs.project_root)
+      # A conservative fast path: leave header inheritance and eligibility to Org.
+      unless File.read(path).match?(/#\+begin_src\b|#\+call:|\bsrc_\w+|\bcall_\w+/i)
+        puts "Skipped: no executable code blocks"
+        return
+      end
+
       expr = <<~ELISP
-        (save-window-excursion
-          (if (get-buffer "#{session_name}")
-            (kill-buffer "#{session_name}"))
-          (with-current-buffer (find-file-noselect "#{README_ORG}")
-            (save-buffer)
-            (require 'ob-ruby)
-            (org-babel-execute-buffer)
-            (save-buffer)
-            "OK"))
+        (with-current-buffer (find-file-noselect #{path.dump})
+          (save-buffer)
+          (require 'ob-ruby)
+          (let ((eligible nil))
+            (let ((org-confirm-babel-evaluate nil))
+              (org-babel-map-executables nil
+                (let ((info (org-babel-get-src-block-info 'light)))
+                  (when (or (null info) (org-babel-check-confirm-evaluate info))
+                    (setq eligible t)))))
+            (if (not eligible)
+                "Skipped: no evaluable code blocks"
+              (let ((session (get-buffer #{session_name.dump})))
+                (when session
+                  (let ((process (get-buffer-process session)))
+                    (when process (set-process-query-on-exit-flag process nil)))
+                  (kill-buffer session)))
+              (org-babel-execute-buffer)
+              (save-buffer)
+              "Babel execution complete")))
       ELISP
 
-      unless system("emacsclient", "--quiet", "--eval", expr)
-        abort "Babel execution failed"
+      run(expr, "Babel execution")
+    end
+
+    def self.export_readme # rubocop:disable Naming/PredicateMethod -- public command, not a predicate
+      check_readme_destination!
+      root = GemDocs.project_root
+      destination = File.join(root, README_MD)
+      Tempfile.create(['.gem_docs-readme-', '.md'], root) do |temporary|
+        export(README_ORG, destination: temporary.path)
+        generated = File.read(temporary.path)
+        check_readme_destination!
+        temporary.rewind
+        temporary.write("#{README_MARKER}\n\n#{generated}")
+        temporary.truncate(temporary.pos)
+        temporary.flush
+        temporary.chmod(File.exist?(destination) ? File.stat(destination).mode & 0o777 : 0o644)
+        File.rename(temporary.path, destination)
       end
+      true
     end
 
-    def self.export
-      expr = <<~ELISP
-        (save-window-excursion
-          (with-current-buffer (find-file-noselect "#{README_ORG}")
-            (save-buffer)
-            (require 'ox-gfm)
-            (org-gfm-export-to-markdown)))
-      ELISP
+    def self.check_readme_destination!
+      destination = File.join(GemDocs.project_root, README_MD)
+      return unless File.exist?(destination) || File.symlink?(destination)
+      return if File.file?(destination) && File.open(destination, &:gets).to_s.chomp == README_MARKER
+
+      raise Error, "Refusing to overwrite #{destination}: missing first-line #{README_MARKER}. " \
+        "Keep handwritten Markdown unchanged. To opt into generation, review/back up the file " \
+        "and add that marker as its first line."
+    end
 
-      system("emacsclient", "--quiet", "--eval", expr)
+    def self.export_changelog
+      export(CHANGELOG_ORG)
     end
 
     def self.session_name
       "*#{Repo.from_gemspec.name}_session*"
     end
+
+    class << self
+      private
+
+      def export(filename, destination: nil)
+        path = File.expand_path(filename, GemDocs.project_root)
+        raise Error, "Cannot export missing file: #{path}" unless File.file?(path)
+
+        expr = <<~ELISP
+          (with-current-buffer (find-file-noselect #{path.dump})
+            (save-buffer)
+            (require 'ox-gfm)
+            #{destination ? "(org-export-to-file 'gfm #{destination.dump})" : '(org-gfm-export-to-markdown)'}
+            #{"Export #{filename} complete".dump})
+        ELISP
+        run(expr, "Export #{filename}")
+      end
+
+      def run(expr, operation)
+        seconds = Float(GemDocs.config.emacs_timeout)
+        raise ArgumentError,
+              "emacs_timeout must be a positive, finite number" unless seconds.positive? && seconds.finite?
+
+        # Fail on prompts rather than leaving emacsclient waiting in the background.
+        wrapped = <<~ELISP
+          (progn
+            (require 'cl-lib)
+            (save-window-excursion
+              (cl-letf (((symbol-function 'yes-or-no-p)
+                         (lambda (&rest args)
+                           (error "GemDocs requires interactive confirmation: %s. Run this operation in Emacs first" (car args))))
+                        ((symbol-function 'y-or-n-p)
+                         (symbol-function 'yes-or-no-p)))
+                (with-timeout (#{seconds} (error "GemDocs timed out: #{operation}"))
+                  #{expr}))))
+        ELISP
+        pid = Process.spawn("emacsclient", "--quiet", "--eval", wrapped)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        loop do
+          result = Process.waitpid2(pid, Process::WNOHANG)
+          if result
+            pid = nil
+            unless result.last.success?
+              raise Error,
+                    "#{operation} failed (emacsclient exit #{result.last.exitstatus.inspect}); see Emacs output above"
+            end
+
+            return true
+          end
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise Error,
+                  "#{operation} timed out after #{seconds}s. " \
+                    "The Emacs server may still be executing; inspect it before retrying."
+          end
+
+          sleep 0.05
+        end
+      rescue Errno::ENOENT
+        raise Error, "#{operation} failed: emacsclient was not found"
+      ensure
+        if pid
+          begin
+            Process.kill("KILL", pid)
+          rescue Errno::ESRCH
+            # The client exited between the timeout and cleanup.
+          end
+          Process.waitpid(pid)
+        end
+      end
+    end
   end
 end

data/lib/gem_docs/header.rb

@@ -18,6 +18,17 @@ module GemDocs
       prelim.any? { |h| h.match?(PROPERTY_RE) }
     end
 
+    def self.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
+
     class << self
       private
 
@@ -38,17 +49,6 @@ module GemDocs
         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

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'strscan'
-require 'debug'
 
 module GemDocs
   module Overview
@@ -26,7 +25,7 @@ module GemDocs
         #
         #{overview.lines.map { |l| l.match?(/\A\s*\z/) ? '#' : "# #{l.rstrip}" }.join("\n")}
       RUBY
-      return false if old_comment == new_comment
+      return false if old_comment.rstrip == new_comment
 
       new_lib =
         if old_match
@@ -35,10 +34,10 @@ module GemDocs
           old_lib.sub(old_comment, new_comment)
         else
           scanner = StringScanner.new(old_lib)
-          if scanner.scan_until(/^module #{repo.module_name}/)
+          if scanner.scan_until(/^(?:class|module) #{Regexp.escape(repo.module_name)}\b/)
             scanner.pre_match + "\n" + new_comment + "\n" + scanner.matched + scanner.rest
           else
-            # No `module GemName` in the file.  Add empty one at the end
+            # No matching class or module in the file. Add an empty module at the end.
             old_lib + "\n" + new_comment + "\nmodule #{repo.module_name}\nend"
           end
         end
@@ -46,18 +45,15 @@ module GemDocs
     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.
+    # the main library file. The Regex requires the comment to come immediately
+    # before the `class <GemName>` or `module <GemName>` line, 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)
+      # Match only comment/blank lines, never Ruby code between the banner and
+      # declaration. This also recognizes legacy empty or duplicated banners.
+      %r{^\#[ ]#{Regexp.escape(BANNER)}[^\n]*
+        (?:\n(?:[ \t]*\#[^\n]*|[ \t]*))*
+        (?=\n(?:class|module)\s+#{Regexp.escape(repo.module_name)}\b)}ix
     end
 
     def self.present?
@@ -82,7 +78,7 @@ module GemDocs
         result = +''
         scanner = StringScanner.new(text)
         heads.each do |h|
-          if scanner.scan_until(/\n(?<head>\s*\*\s+#{Regexp.escape(h)})[^\n]*\n/)
+          if scanner.scan_until(/^(?<head>\* +#{Regexp.escape(h)})(?=[ \t\n]|\z)[^\n]*\n/)
             this_head = scanner.named_captures['head'] + "\n"
             body_start = scanner.pos
             body_end =
@@ -95,6 +91,8 @@ module GemDocs
             result << this_head + scanner.string[body_start..body_end]
           end
         end
+        return if result.empty?
+
         result.sub(/\A\n*/, '')
       end
     end

data/lib/gem_docs/repo.rb

@@ -2,13 +2,14 @@
 
 module GemDocs
   class Repo
-    attr_accessor :root, :host, :user, :name, :module_name
+    attr_accessor :root, :host, :user, :name, :module_name, :version
     attr_accessor :branch, :workflow_dir, :workflow_name
 
     def initialize(root: nil, host: nil,
       user: nil,
       name: nil,
       module_name: nil,
+      version: nil,
       branch: 'master',
       workflow_dir: nil,
       workflow_name: nil)
@@ -16,6 +17,7 @@ module GemDocs
       @host = host
       @user = user
       @module_name = module_name
+      @version = version
       @name = name
       @branch = branch
       @workflow_dir = workflow_dir
@@ -59,6 +61,7 @@ module GemDocs
           user: user,
           name: name,
           module_name: mname,
+          version: spec.version.to_s,
           branch: branch,
           workflow_dir: wdir,
           workflow_name: wname,
@@ -72,7 +75,7 @@ module GemDocs
             GemDocs.config.repo_workflow_dir,
             GemDocs.config.repo_workflow_name,
           )
-          return [File.dirname(workflow_file), File.dirname(workflow_file)] if File.readable?(workflow_file)
+          return [File.dirname(workflow_file), File.basename(workflow_file)] if File.readable?(workflow_file)
         end
 
         dir = File.join(GemDocs.project_root, ".github/workflows")
@@ -149,7 +152,7 @@ module GemDocs
           abort "No gemspec found" if candidates.empty?
           abort "Multiple gemspecs found: #{candidates.join(', ')}" if candidates.size > 1
         end
-        candidates.first
+        File.join(GemDocs.project_root, candidates.first)
       end
 
       def load_gemspec(path)

data/lib/gem_docs/skeleton.rb

@@ -2,15 +2,17 @@
 
 module GemDocs
   module Skeleton
-    PROPERTY_RE = /^#\+PROPERTY:\s+header-args:ruby/
+    VERSION_BLOCK_RE = /^# gem_docs:version begin\n.*?^# gem_docs:version end\n?/m
 
-    # @return String The overview from README per config
+    # Create the README or refresh its managed gemspec version block.
+    # @return [Boolean] whether the README changed
     def self.make_readme?
-      return false if present?
-
       repo = Repo.from_gemspec
+      return write_version?(File.read(README_ORG), repo.version) if readme_present?
+
       content = <<~SKEL
         #+TITLE: #{repo.module_name} Guide
+        #{Header.org_headers.strip}
 
         * Introduction
 
@@ -44,11 +46,54 @@ module GemDocs
         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
+      write_version?(content, repo.version)
     end
 
-    def self.present?
+    def self.write_version?(content, version)
+      block = <<~ORG
+        # gem_docs:version begin
+        Version: #{version}
+        # gem_docs:version end
+      ORG
+      updated = if content.match?(VERSION_BLOCK_RE)
+        content.sub(VERSION_BLOCK_RE, block)
+      else
+        # Keep the version below the initial Org metadata and near the CI badge.
+        header = content[/\A(?:#\+[^\n]*\n)*/]
+        header + "\n" + block + "\n" + content.delete_prefix(header)
+      end
+      return false if File.exist?(README_ORG) && updated == content
+
+      File.write(README_ORG, updated)
+      true
+    end
+    private_class_method :write_version?
+
+    def self.readme_present?
       File.exist?(README_ORG)
     end
+
+    def self.make_changelog?
+      return false if changelog_present?
+
+      content = <<~SKEL
+        * COMMENT CHANGELOG tips:
+        1. Don't dump your git change logs into this file, write them yourself.
+        2. Keep entries short and user-focused,
+        3. Use non-technical language, but do speak in the vocabulary of your gem.
+        4. Don't document changes only of interest to the programmers, just those the
+           user would find useful.
+        5. Give each heading a version number and an inactive date (C-c ! is useful here).
+
+        * Version 0.3.0 [2025-12-27 Sat]
+        - First change
+        - Second change
+      SKEL
+      File.write(CHANGELOG_ORG, content) > 0
+    end
+
+    def self.changelog_present?
+      File.exist?(CHANGELOG_ORG)
+    end
   end
 end

data/lib/gem_docs/tasks.rb

@@ -4,43 +4,67 @@ module GemDocs
   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
+      GemDocs::Emacs.export_readme
+    end
+
+    file CHANGELOG_MD => CHANGELOG_ORG do
+      print "Exporting \"#{CHANGELOG_ORG}\" → "
+      GemDocs::Emacs.export_changelog
     end
 
     namespace :docs do
+      task :check_readme do
+        GemDocs::Emacs.check_readme_destination!
+      end
+
+      desc "Suggest documentation improvements without changing files or running examples"
+      task :doctor do
+        GemDocs::Doctor.run
+      end
+
       desc "Evaluate code blocks in README.org"
-      task :tangle => [:skeleton] do
+      task :tangle => ["docs:skeleton:readme"] do
         print "Executing code blocks in #{README_ORG} ... "
         GemDocs::Emacs.tangle
       end
 
       desc "Export README.org → README.md"
-      task :export => [:badge, README_MD]
+      task :export => [:check_readme, :badge, README_MD, CHANGELOG_MD]
 
       desc "Extract overview from README.org and embed in lib/<gem>.rb for ri/yard"
-      task :overview => [:skeleton, README_ORG] do
+      task :overview => ["docs:skeleton:readme", 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"
+          puts "unchanged (already current or no matching overview)"
         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"
+      namespace :skeleton do
+        desc "Create README.org if missing and refresh its gem version"
+        task :readme do
+          if GemDocs::Skeleton.make_readme?
+            puts "README.org created or version updated"
+          else
+            puts "README.org already up to date"
+          end
+        end
+
+        desc "Create skeleton CHANGELOG.org if one does not exist"
+        task :changelog do
+          if GemDocs::Skeleton.make_changelog?
+            puts "CHANGELOG.org added"
+          else
+            puts "CHANGELOG.org already present"
+          end
         end
       end
 
       desc "Insert #+PROPERTY headers at top of README.org for code blocks"
-      task :header => :skeleton do
+      task :headers => "docs:skeleton:readme" do
         print "Inserting headers ... "
         if GemDocs::Header.write_header?
           puts "added"
@@ -49,6 +73,8 @@ module GemDocs
         end
       end
 
+      task :header => :headers
+
       desc "Generate YARD HTML documentation"
       task :yard => [:overview] do
         puts "Generating YARD documentation ... "
@@ -56,7 +82,7 @@ module GemDocs
       end
 
       desc "Ensure GitHub Actions badge exists in README.org"
-      task :badge => :skeleton do
+      task :badge => "docs:skeleton:readme" do
         print "Ensuring badges are in README.org ... "
         if GemDocs::Badge.ensure!
           puts "added"
@@ -66,7 +92,16 @@ module GemDocs
       end
 
       desc "Run all documentation tasks (examples, readme, overview, yard, ri)"
-      task :all => [:skeleton, :header, :tangle, :export, :overview, :yard]
+      task :all => [
+        :check_readme,
+        "docs:skeleton:readme",
+        "docs:skeleton:changelog",
+        :headers,
+        :tangle,
+        :export,
+        :overview,
+        :yard
+      ]
     end
   end
 end

data/lib/gem_docs/version.rb

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

data/lib/gem_docs/yard.rb

@@ -31,11 +31,11 @@ module GemDocs
         YOPTS
       end
 
-      # Write .yardopts only if needed
+      # Create defaults only when the project has no .yardopts file.
       def write_yardopts
-        if !File.exist?(yardopts_path) || File.read(yardopts_path) != yardopts_contents
-          File.write(yardopts_path, yardopts_contents)
-        end
+        return if File.exist?(yardopts_path)
+
+        File.write(yardopts_path, yardopts_contents)
       end
     end
   end

data/lib/gem_docs.rb

@@ -37,6 +37,7 @@ require "fileutils"
 #   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~
+# - exporting ~CHANGELOG.org~ to Git-flavored markdown in ~CHANGELOG.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
@@ -49,7 +50,16 @@ require "fileutils"
 # detains filled in.  If there is already a README.org file, it does nothing.
 #
 # #+begin_src ruby :eval no
-#  rake docs:skeleton
+#  rake docs:skeleton:readme
+# #+end_src
+#
+# ** Create a skeleton CHANGELOG.org file
+# This is a simple task that creates a bare-bones ~CHANGELOG.org~ file to get
+# started with.  It only contains some tips for writing a change log and a
+# sample heading.  If there is already a CHANGELOG.org file, it does nothing.
+#
+# #+begin_src ruby :eval no
+#  rake docs:skeleton:changelog
 # #+end_src
 #
 # ** Add proper ~#+PROPERTY~ headers in ~README.org~: ~rake docs:headers~
@@ -208,7 +218,7 @@ require "fileutils"
 # 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~
+# ** Export ~README.org~ and ~CHANGELOG.org~ to Markdown: ~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.
@@ -229,6 +239,10 @@ require "fileutils"
 # 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~
 #
+# Less important, but still handy, you can also write the CHANGELOG in org mode
+# and this task will convert it to markdown for display on github and
+# rubygems.org.
+#
 # #+begin_src ruby :eval no
 #   rake docs:export
 # #+end_src
@@ -271,15 +285,24 @@ module GemDocs
   require_relative "gem_docs/badge"
   require_relative "gem_docs/header"
   require_relative "gem_docs/skeleton"
+  require_relative "gem_docs/doctor"
   require_relative "gem_docs/tasks"
 
   README_ORG = "README.org"
   README_MD = "README.md"
+  CHANGELOG_ORG = "CHANGELOG.org"
+  CHANGELOG_MD = "CHANGELOG.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
+    loop do
+      return here unless Dir.glob(['*.gemspec', 'Gemfile'], base: here).empty?
+
+      parent = File.dirname(here)
+      return here if parent == here
+
+      here = parent
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gem_docs
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 2025-12-24 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.28
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.28
 description: Shared tasks for README.org code block execution, markdown export, YARD
   integration, etc.
 email:
@@ -48,6 +48,7 @@ files:
 - lib/gem_docs.rb
 - lib/gem_docs/badge.rb
 - lib/gem_docs/config.rb
+- lib/gem_docs/doctor.rb
 - lib/gem_docs/emacs.rb
 - lib/gem_docs/header.rb
 - lib/gem_docs/overview.rb
@@ -76,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Documentation automation for Ruby gems
 test_files: []