search

dakrone / clj-http

An idiomatic clojure http client wrapping the apache client. Officially supported version.
http://clojars.org/clj-http
MIT License
1.78k stars 411 forks source link

Export README.md from .org for cljdoc #518

Open holyjak opened 5 years ago

holyjak commented 5 years ago

https://cljdoc.org/ is a popular single-source-for-all-libs documentation hub so it would be ideal if the much used clj-http showed up well there. However it doesn't currently because cljdoc currently only supports .md and .adoc files while here we have an .org.

A solution would be to either export .md from the .org file (perhaps in a git push hook?) or to add .org support to Cljdoc.

rymndhng commented 5 years ago

This sounds like a good idea! @dakrone do you have any preference of an approach.

I've thought about a few ways to go about this.

  1. Write a build script that generates README.md at build time. This could be done with an emacs script, hypothetically. I took a stab at this and found some issues with the current org file settings. I had to disable org-babel and the TOC generation to get export as markdown working. If we choose this strategy, we'd need to tweak the org file settings such that it's repeatable.

  2. Migrate to markdown moving forward. This means doing a one-time pass to convert README.org to README.md and use it moving forward.

  3. Stick with org and wait it out until org support in cljdoc. There are no JVM-based org to HTML translators. However, it may be possible to reduce some effort spent on output generation if cljdoc can translate orgmode AST to flexmark AST. orgzly has a org-parser library which looks like a promising starting point -- that could be a fun project 🤷‍♂️

Ultimately, I think this depends on having the maintainer have final weigh in on the workflow. @dakrone if there's one strategy you prefer, I could take a stab at doing the work. :)

dakrone commented 5 years ago

I don't mind switching the readme to Markdown, as not everyone uses org-mode (even though I enjoy Org more than Markdown :)). @rymndhng go ahead and do the conversion!

holyjak commented 5 years ago

BTW pandoc can covnert org-mode to markdown, I believe.