robertluo / clerk-doc

Turn clojure files into markdown

(ns robertluo.clerk-doc.readme
  (:require [robertluo.clerk-doc :as doc]
            [robertluo.clerk-doc.ai :as ai])) ;=> nil

io.github.robertluo/clerk-doc

Turns Clojure source files into Markdown. Usually clerk notebooks are good candidates for when you do not feel like writing a README.md file for your Github project.

Usage

1. Write a Clojure source file, just like this.
2. Add an alias in your deps.edn.
3. Call it by clojure -X:clerk-doc.

(comment
  {:clerk-doc {:extra-deps {io.github.robertluo/clerk-doc {:git/tag "v0.2.1" :git/sha "xxxxxx"}}
               :exec-fn    robertluo.clerk-doc/clj->md
               :exec-args  {:from "your-source.clj" :to "README.md"
                            :eval-code? true :ai-improve? false}}}
  ) ;=> nil

Goodies

• If :eval-code? is set to true, the Clojure code in the file will be evaluated, and the result will be appended to the generated code blocks.
• Thanks to openai-clojure, the :ai-improve? flag uses OpenAI to improve your resulting Markdown file. You need to set up your environment; please refer to the link above. Make sure to check the result after ChatGPT's work; it sometimes surprises me.

You have to have a paid account with OpenAI, otherwise the OpenAI's rate limit will generate a 400 error for anything longer than one simple sentence.

Changes

• v0.2.0: Improved eval to print out exceptions and nils

UnLicense

Copyright (c) 2023 Robert Luo