This is fantastic! I wonder if its worth evolving it into something like https://yardoc.org. Where there is a bit of https://github.com/lsegal/yard/blob/main/docs/Tags.md you can put in the comments: > YARD uses a ‘@tag’ style definition syntax (like Python, Java, Objective-C and other languages) for meta tags alongside regular code documentation. These tags should be able to happily sit side by side RDoc formatted documentation, but provide a much more consistent and usable way to describe important information about objects, such as what parameters they take and what types they are expected to be, what type a method should return, what exceptions it can raise, if it is deprecated, etc.. It also allows information to be better (and more consistently) organizedduring the output generation phase. You can find a list of tags in the Tags.md file.

Such a tool would be more adapted for types and function documentation (like what Codox does), not for a « notebook » like what I’ve imagined at first but it’s definitely doable with additional parsing steps

But I’ve speed read their doc, possibly missed what you meant :)

Have it up-and-running with babashka and cmdline argument parsing:

#!/usr/local/bin/bb
;; Run like this:  bb bb-cookbook.clj
;; Arguments help: bb bb-cookbook.clj -h
;; Normal use:     bb bb-cookbook.clj -i "./inputpath" -o "./outputpath"
;;
;; -- insert code from the blog here --
;;

(defn valid-path? [path]
  (.exists (io/file path)))

(def validate-msg "path does not exist")

(def cli-options
  [["-i" "--inputpath INPUTPATH" "String that represents the directory to the input files"
    :default "./inputpath"
    :parse-fn identity
    :validate [valid-path? validate-msg] ]
   ["-o" "--outputpath OUTPUTPATH" "String that represents the path to where the output should be stored"
    :default  "./outputpath"
    :parse-fn identity
    :validate [valid-path? validate-msg]]
   ["-h" "--help"]])

(def options (clojure.tools.cli/parse-opts *command-line-args* cli-options))

(when (:errors options)
  (println (:errors options))
  (System/exit 1))

(when ((comp :help :options) options)
  (println (:summary options))
  (System/exit 1))

(compile-cookbooks 
  ((comp :inputpath :options) options) 
  ((comp :outputpath :options) options))

(:require [clj-time.core :as t])

clj-time should not be used anymore, the library is effectively deprecated. use java.time instead

(Quick lunchtime test to get a feel for the cookbook ... It's nice! Could be useful :thinking_face: )

@cyppan Yes, I was thinking more the use case as an enhanced codox . I feel very frustrated with the minimal ability to document code with those tools and would love a way to have more enriched ways to structurally / annotated / document the details of code in a way similar to Yard. Not only for the writing side, but haven more enriched documentation in the output side to help the consumer of the documentation.

Ok I understand, the point of my script was to be able to execute code from top level forms to put in the doc in dedicated notebook files, but I guess It could be put in rich comments instead, or in a macro which would run the code inside based on some env config, this way the documentation could be generated from the actual code. Regarding the doc about fn args, return values and others, I would love something based on clj metadata, or spec/prismatic/malli schemas, instead of string conventions