A script that reads a single ClojureScript namespace, like `re-frame.core`, 
and outputs a single page of markdown-based API documentation. This markdown
can then be fed into your Static Site Generator. 

Usage: clojure -m ns-to-markdown ../src/re_frame/core.cljc > api-re-frame.core.md

Notes:
  - run as a script using the Clojure CLI
  - the first argument is a path to a file containing a ClojureScript namespace. 
  - it reads the namespace using the ClojureScript analyzer, extracting public
    var metadata such as function names, arglists and docstrings.
  - it then writes a single markdown-based API doc to stdout
  - you can see an example of the output here: http://day8.github.io/re-frame/api-re-frame.core/ 
    But only take note of the central content. The navigation sidebars are automatically 
    generated by our Static Site Generator (mkdocs) working off H2/H3 elements. They are 
    not created by this script.

Workflow: 
  - the output is designed to be incorporated into a Static Site generator, like `mkdocs`.
  - For re-frame, we use it as a step within the GitHub Actions workflow which builds docs. See: 
    https://github.com/day8/re-frame/blob/78ca09785e2adf9eea11f1e4bff2477d193f4b46/.github/workflows/docs-workflow.yml#L15

About The Namespace:
  - examine this example: https://github.com/day8/re-frame/blob/master/src/re_frame/core.cljc
  - notice the docstrings are specifically written to be markdown-compatible.
  - notice the `:api-docs` hack (search for it) used to group vars under headings in the final output.
  - the target for re-frame is `mkdocs`, so notice the use of `#!clj` ahead of code blocks. 
    Which exploits the `mkdocs` feature `pymdownx.inlinehilite`. But that's a choice - it isn't required.