Documentation making tool?

[didibus]

Is there a tool that generates documentation for a project in the form of a single markdown file?

Where it would have namespaces, functions, and their corresponding doc-strings?

[mvarela]

I’m only familiar with Marginalia and Codox, and I think neither generates markdown, though you might be able to convert Marginalia’s output to markdown via pandoc.

edit: nevermind, if you run pandoc on Marginalia’s output, it generates a a huge markdown table, which is probably not what you need.

[jwhitlark]

Not as such, but you can easily use https://clojars.org/codox to generate that yourself.

include codox {:mvn/version "0.10.5"} in your deps, open a repl, (codox.reader.clojure/read-namespaces) will give you easy access to everything you want.

The structure of the result is by namespace, then includes lots of info on everything publicly available.

The keys in the maps are:
:name   - the name of the namespace
:doc    - the doc-string on the namespace
:author - the author of the namespace
:publics
  :name       - the name of a public function, macro, or value
  :file       - the file the var was declared in
  :line       - the line at which the var was declared
  :arglists   - the arguments the function or macro takes
  :doc        - the doc-string of the var
  :type       - one of :macro, :protocol, :multimethod or :var
  :added      - the library version the var was added in
  :deprecated - the library version the var was deprecated in

[martinklepsch]

If your library is on Clojars or Maven Central you can also give https://cljdoc.org a try. It exposes a similar feature set as codox but builds documentation automatically and without any setup.

There’s a search on the frontpage but you can also go to documentation directly by going to:

https://cljdoc.org/d/$group_id/$artifact_id

If your project name doesn’t contain a slash the group and artifact ID are the same.