gem_docs 0.1.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46cf522895c0d4958b6547d69fbb1f28146d6981b2c73ba448be8a12c05ed407
-  data.tar.gz: dfc8f1ff2ce78bb680ddaeb0384718a47d80b7aa718a17ce5fef678f630c4957
+  metadata.gz: 5e1d29bbce836d7be31883f9748134af47f3c2d6e160b35639f7195cf3ab23d6
+  data.tar.gz: f01a2d4a987020c7dad7f18a3d4ebd3145c2326d069ad9b3b5e20348e6b56d4e
 SHA512:
-  metadata.gz: 3d419c689f20a889a207d27cc16c8552611d5e150e1672921bf934f3f83edefb61aad9aa5792138984f6b147fdfa5b2b5939a902dd3920d097ca0173369cc722
-  data.tar.gz: b938002904d804b90c6eb96374adac93ff60ee4d23e08b47ccdd29ea27ac81684c90be6d3e5d22e00c68943f0d84ba493453905b278a4b4c519b9ed737575c95
+  metadata.gz: 2163336ebab1ea2d2e7eed04b98aa8f2bb6da856a3184342fcb6e6d675e73a131fe6eeaf5707ddae1e35681c873d31044f85cf9c0c90f9ccb8d94972f32adbfa
+  data.tar.gz: 41f5ca7c522e9fd18d462e1b5f9a5a020e6a0ee4a5cbeab645b93c76b8342c37cf2064acf27eae6d657497485a036ca9a8502cf9b314bf13e3dc3a32764737a7

data/lib/gem_docs/config.rb

@@ -20,6 +20,7 @@ module GemDocs
           #+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+ :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/emacs.rb

@@ -3,9 +3,10 @@
 module GemDocs
   module Emacs
     def self.tangle
-      # ensure_saved
       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)
@@ -14,24 +15,43 @@ module GemDocs
             "OK"))
       ELISP
 
-      if system("emacsclient", "--quiet", "--eval", expr)
-        FileUtils.touch(STAMP)
-      else
+      unless system("emacsclient", "--quiet", "--eval", expr)
         abort "Babel execution failed"
       end
     end
 
-    def self.export
-      # ensure_saved
+    def self.export_readme
       expr = <<~ELISP
         (save-window-excursion
           (with-current-buffer (find-file-noselect "#{README_ORG}")
             (save-buffer)
             (require 'ox-gfm)
-            (org-gfm-export-to-markdown)))
+            (org-gfm-export-to-markdown))
+          (with-current-buffer (find-file-noselect "#{CHANGELOG_ORG}")
+            (save-buffer)
+            (require 'ox-gfm)
+            (org-gfm-export-to-markdown))
+           "Export README complete")
       ELISP
 
       system("emacsclient", "--quiet", "--eval", expr)
     end
+
+    def self.export_changelog
+      expr = <<~ELISP
+        (save-window-excursion
+          (with-current-buffer (find-file-noselect "#{CHANGELOG_ORG}")
+            (save-buffer)
+            (require 'ox-gfm)
+            (org-gfm-export-to-markdown))
+           "Export CHANGELOG complete")
+      ELISP
+
+      system("emacsclient", "--quiet", "--eval", expr)
+    end
+
+    def self.session_name
+      "*#{Repo.from_gemspec.name}_session*"
+    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/skeleton.rb

@@ -2,11 +2,9 @@
 
 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?
+      return false if readme_present?
 
       repo = Repo.from_gemspec
       content = <<~SKEL
@@ -47,8 +45,31 @@ module GemDocs
       File.write(README_ORG, content) > 0
     end
 
-    def self.present?
+    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

@@ -1,35 +1,31 @@
 # 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
+      GemDocs::Emacs.export_readme
     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)
+    file CHANGELOG_MD => CHANGELOG_ORG do
+      print "Exporting \"#{CHANGELOG_ORG}\" → "
+      GemDocs::Emacs.export_changelog
     end
 
     namespace :docs do
       desc "Evaluate code blocks in README.org"
-      task :tangle => [:skeleton, STAMP]
+      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 => [: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"
@@ -38,17 +34,28 @@ module GemDocs
         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 skeleton README.org if one does not exist"
+        task :readme do
+          if GemDocs::Skeleton.make_readme?
+            puts "README.org added"
+          else
+            puts "README.org already present"
+          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 :header => "docs:skeleton:readme" do
         print "Inserting headers ... "
         if GemDocs::Header.write_header?
           puts "added"
@@ -64,9 +71,8 @@ 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"
         else
@@ -75,7 +81,7 @@ module GemDocs
       end
 
       desc "Run all documentation tasks (examples, readme, overview, yard, ri)"
-      task :all => [:skeleton, :header, :tangle, :export, :overview, :yard]
+      task :all => ["docs:skeleton:readme", "docs:skeleton:changelog", :header, :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.1.2"
+  VERSION = "0.3.1"
 end

data/lib/gem_docs.rb

@@ -11,10 +11,7 @@ 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
@@ -40,24 +37,32 @@ 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
 #   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
+#  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~
-# **
 # Getting emacs code blocks to render well in your ~README.org~ takes proper
 # configuration of the code block headers in Emacs.
 #
@@ -113,7 +118,13 @@ require "fileutils"
 # 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:
+# they work.
+#
+# *** Output Tables
+# You can build table for ~org~ to display in the output by returning an array
+# of arrays, which org-mode renders as a table in the output.  You can add an
+# hline to the output table by simply adding ~nil~ to the outer array where you
+# want the hline to occur.
 #
 # #+begin_src ruby
 #   result = []
@@ -142,10 +153,25 @@ require "fileutils"
 # | 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.
+# *** Output Values
+# Sometimes, however, you just want the result of the code block evaluated
+# without building a table.  To do so, just set the block header to ~:results
+# value raw~.
+#
+# To compute the value of an $1,000 asset gaining 5% continuously compounding
+# interest over four years, you might do this:
+#
+# #+begin_src ruby :results value raw
+#   rate = 0.05
+#   time = 4
+#   principal = 1000
+#   principal * Math.exp(rate * time)
+# #+end_src
+#
+# #+RESULTS:
+# #+begin_example
+# 1221.40275816017
+# #+end_example
 #
 # 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
@@ -174,6 +200,11 @@ require "fileutils"
 #  rake docs:tangle
 # #+end_src
 #
+# With the default headers provided by `rake docs:headers`, the buffer is
+# evaluated in a session so that code blocks can build on one another.  However,
+# `docs:tangle` kills any existing session buffer before it runs so that each
+# buffer evaluation is independent of earlier runs.
+#
 # ** 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
@@ -187,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.
@@ -208,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
@@ -254,6 +289,8 @@ module GemDocs
 
   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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gem_docs
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.1
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 2025-12-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -76,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Documentation automation for Ruby gems
 test_files: []