RubyGems - gem_docs - Versions diffs - 0.1.0 → 0.2.0 - Mend

gem_docs 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a07d76db2fbb75383d41735198a4cbf7b1d2b6515653df77e21e8c9575a40ade
-  data.tar.gz: 65e3554324e7c91e8466efba2d032c53d8549e64a7a460cce4ee4d7322fffa40
+  metadata.gz: 5eadd7f7e5421dca33c5297a35fd54283a002b6f87757796aaa697e5ba39ce50
+  data.tar.gz: 3dd763c1846d02c694a0c9aa85a56e59cae9be90a661778dc94a0ab95a5ba971
 SHA512:
-  metadata.gz: 0d9090c6ac05d0d80fb556019bb56c57fbcdd3e1b691e1b38d5b54da8bca5923c00dae9a6e18f616bad189b3c61c981f5d341294c0ccb46e1afde7274569452c
-  data.tar.gz: 86a7c664a77405127a46e03a2233cc20958613965ca6bd3beba2a0ca1ae342192f835a26d22d18ad6f045a6d9f79eb13934942fe0f4baab4a11d17adbc9400dd
+  metadata.gz: e18a7cdf17f776fca792566409e1b9d5f9ab1119e20980d7d204f116204461dd6e335b5bcb79ad5ba5d05abc6594780517e76fe4f86458d8b15c1fd0a8d1df0f
+  data.tar.gz: baef0a42000b8f28f8721e3502b694669a8a1c335f5a82f2bd45344e10494bfffe792e93e83bcfba8470fdad1ab533b0b1ada895def53ec4a1b3a0c088f64cf7

data/lib/gem_docs/emacs.rb CHANGED Viewed

@@ -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,15 +15,12 @@ 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
       expr = <<~ELISP
         (save-window-excursion
           (with-current-buffer (find-file-noselect "#{README_ORG}")
@@ -33,5 +31,9 @@ module GemDocs
       system("emacsclient", "--quiet", "--eval", expr)
     end
+    def self.session_name
+      "*#{Repo.from_gemspec.name}_session*"
+    end
   end
 end

data/lib/gem_docs/header.rb CHANGED Viewed

@@ -9,7 +9,7 @@ module GemDocs
       return false if present?
       prelim, body = extract_prelim_body
-      new_org = prelim.join.strip + org_headers.strip + "\n\n" + body.join
+      new_org = prelim.join.strip + "\n" + org_headers.strip + "\n\n" + body.join
       File.write(README_ORG, new_org) > 0
     end
@@ -32,9 +32,6 @@ module GemDocs
             body << line
           elsif in_prelim && (line.match(/^#/) || line.match(/^\s*$/))
             prelim << line
-          # elsif in_prelim
-          #   in_prelim = false
-          #   body << line
           else
             body << line
           end

data/lib/gem_docs/overview.rb CHANGED Viewed

@@ -35,8 +35,12 @@ module GemDocs
           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
+          if scanner.scan_until(/^module #{repo.module_name}/)
+            scanner.pre_match + "\n" + new_comment + "\n" + scanner.matched + scanner.rest
+          else
+            # No `module GemName` in the file.  Add empty one at the end
+            old_lib + "\n" + new_comment + "\nmodule #{repo.module_name}\nend"
+          end
         end
       File.write(target, new_lib) > 0
     end
@@ -79,7 +83,7 @@ module GemDocs
         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"
+            this_head = scanner.named_captures['head'] + "\n"
             body_start = scanner.pos
             body_end =
               if scanner.scan_until(/\n^\s*\*[^\*\n]+/)
@@ -91,7 +95,7 @@ module GemDocs
             result << this_head + scanner.string[body_start..body_end]
           end
         end
-        result
+        result.sub(/\A\n*/, '')
       end
     end
   end

data/lib/gem_docs/tasks.rb CHANGED Viewed

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 module GemDocs
-  extend Rake::DSL
-  STAMP = ".tangle-stamp"
   def self.install
     extend Rake::DSL
@@ -14,16 +10,12 @@ module GemDocs
       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]
+      task :tangle => [:skeleton] do
+        print "Executing code blocks in #{README_ORG} ... "
+        GemDocs::Emacs.tangle
+      end
       desc "Export README.org → README.md"
       task :export => [:badge, README_MD]
@@ -66,7 +58,6 @@ module GemDocs
       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

data/lib/gem_docs/version.rb CHANGED Viewed

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

data/lib/gem_docs.rb CHANGED Viewed

@@ -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
@@ -46,7 +43,6 @@ require "fileutils"
 #   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
@@ -57,7 +53,6 @@ require "fileutils"
 # #+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 +108,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 +143,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 +190,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

metadata CHANGED Viewed

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gem_docs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 2025-12-23 00:00:00.000000000 Z
+date: 2025-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -27,18 +27,18 @@ dependencies:
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0'
   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.
+        version: '0'
+description: Shared tasks for README.org code block execution, markdown export, YARD
+  integration, etc.
 email:
 - ded@ddoherty.net
 executables: []