Quickdoc

API docs

Rationale

This library came out of the desire to have a fast and light weight tool that produces API docs from any Clojure code (.clj, .cljs, .cljc) without executing that code. This tool produces pure Markdown that you can read directly on Github and the output does not need CSS or JavaScript.

Quickdoc's properties:

Based on clj-kondo static analysis
Fast to run using babashka (around 100ms for this project)

Projects using quickdoc

Status

This project is just getting started. Therefore the API may still undergo significant changes based on early usage and feedback.

Babashka

task

Use as a babashka dependency and task:

# bb.edn
:tasks {
,,,
quickdoc {:doc "Invoke quickdoc"
          :extra-deps {io.github.borkdude/quickdoc {:git/sha "7c8bef54eda28367193ec433af01bb940114f012"}}
          :task (exec 'quickdoc.api/quickdoc)
          :exec-args {:git/branch "master"
                      :github/repo "https://github.com/clj-kondo/clj-kondo"
                      :source-paths ["src/clj_kondo/core.clj"]}}
,,,
}

Now you can run bb quickdoc and your API docs will be generated in API.md.

bbin

Install via bbin:

bbin install io.github.borkdude/quickdoc --as quickdoc

Clojure CLI

Add the following alias to your global or project-local deps.edn:

:aliases {
,,,
:quickdoc
{:deps {org.babashka/cli {:mvn/version "0.4.36"}
        io.github.borkdude/quickdoc
        {:deps/root "jvm"
         :git/sha "7c8bef54eda28367193ec433af01bb940114f012"}}
 :main-opts ["-m" "babashka.cli.exec" "quickdoc.api" "quickdoc"]}
,,,
}

Then you can call quickdoc using:

clj -M:quickdoc :github/repo https://github.com/clj-kondo :git/branch master

You can add default arguments to :exec-args in the alias:

:quickdoc
{,,,
 :exec-args {:github/repo "https://github.com/clj-kondo"
             :git/branch "master"}

So the command line invocation simply becomes:

clj -M:quickdoc

Clojure tool

Quickdoc is also available as a clj tool. Note that this way of invoking quickdoc is slower to start than with babashka.

To install, run:

clj -Ttools install io.github.borkdude/quickdoc '{:deps/root "jvm" :git/sha "<latest-sha>"}' :as quickdoc

Then invoke quickdoc using:

clj -Tquickdoc quickdoc '{:github/repo "https://github.com/borkdude/quickdoc"}'

Can it be improved to do ...?

Probably yes! Let me know in Github Discussions or create an issue.

License

See LICENSE.

borkdude / quickdoc

readme