gem_docs 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eadd7f7e5421dca33c5297a35fd54283a002b6f87757796aaa697e5ba39ce50
-  data.tar.gz: 3dd763c1846d02c694a0c9aa85a56e59cae9be90a661778dc94a0ab95a5ba971
+  metadata.gz: 5e1d29bbce836d7be31883f9748134af47f3c2d6e160b35639f7195cf3ab23d6
+  data.tar.gz: f01a2d4a987020c7dad7f18a3d4ebd3145c2326d069ad9b3b5e20348e6b56d4e
 SHA512:
-  metadata.gz: e18a7cdf17f776fca792566409e1b9d5f9ab1119e20980d7d204f116204461dd6e335b5bcb79ad5ba5d05abc6594780517e76fe4f86458d8b15c1fd0a8d1df0f
-  data.tar.gz: baef0a42000b8f28f8721e3502b694669a8a1c335f5a82f2bd45344e10494bfffe792e93e83bcfba8470fdad1ab533b0b1ada895def53ec4a1b3a0c088f64cf7
+  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

@@ -20,13 +20,31 @@ module GemDocs
       end
     end
 
-    def self.export
+    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)

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

@@ -4,24 +4,28 @@ 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
       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 => [: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"
@@ -30,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"
@@ -56,7 +71,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 +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.2.0"
+  VERSION = "0.3.1"
 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
@@ -275,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.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 2025-12-24 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: []