[HN Gopher] Writing Literate API Documentation in Emacs Org Mode
___________________________________________________________________
Writing Literate API Documentation in Emacs Org Mode
Author : joseph8th
Score : 49 points
Date : 2022-01-29 19:41 UTC (3 hours ago)
(HTM) web link (joseph8th.github.io)
(TXT) w3m dump (joseph8th.github.io)
| thewakalix wrote:
| It would probably be better to remove "Wow" from the title.
| joseph8th wrote:
| But then what would I do with all this extra hyperbole?
| laerus wrote:
| The WOW for me is that a couple of days ago I was looking for
| info on exactly how to do this, so tyvm for writing this. The
| links on the article seem off btw.
| joseph8th wrote:
| Sorry! Fixed the links. Thanks for point it out. It was
| WOMMing.
| dang wrote:
| OK, we've dewowed the title above.
| kristjansson wrote:
| Great summary! I use restclient to produce example calls for
| READMEs and stuff but I hadn't thought to export an html view.
|
| While this really exercises the markup features of org-mode and
| org-babel, wouldn't literate programming have all this
| interleaved with the implementation at the API you're
| documentating?
| joseph8th wrote:
| This approach would work just as well to document and develop,
| for example, a local Python API. Instead of using `restclient`
| source blocks, we'd be using Python blocks. Otherwise, it's the
| same idea.
|
| In my case, I'm documenting RESTful APIs for clients who want
| to write their own client code.
| buscoquadnary wrote:
| I thought literate program was a farsical esoterica that was only
| born because of it's ivory tower surroundings, and would've
| stillborn had it come into the world any other way.
|
| Until I found org-mode it really is world changing if I had
| picked up Doom Emacs for no other reason than org mode it
| would've been well worth it. I have now seriously considered
| trying to do literate program with org mode.
|
| It's already seeped into every project I work on now has a
| notes.org where I keep kind of a stream of consciousness notes of
| what I am doing and copy and paste any code or command I have
| into it for future reference and it has already multipled my
| productivity.
|
| I love org mode and for any person that is already a vimmer I
| recommend highly you pick up Doom Emacs and spend some time
| getting to become familiar with it, especially org mode and magit
| it really is world changing. I can't imagine ever going back.
| jamra wrote:
| Can you compare feature sets from magit to vim fugitive? I've
| always heard nice things about magit but nobody has verbalized
| it in comparison to what vim offers.
| joseph8th wrote:
| I always liked the idea, but I was a pure math major, CS minor.
| Turns out I was better at programming that proof-writing, but
| Literate Programming is associated with the "Ivory Tower
| Academic Elite" because it really is handy.
|
| Jupyter notebooks can provide a literate programming experience
| as well, but the plain-text experience of Org is something
| special.
| moeris wrote:
| I wrote something similar at my last job. Mostly because the
| frontend devs wanted good documentation, and the docs kept
| falling out of sync with the codebase. So I integrated it with a
| test framework:
| https://github.com/savantgroup/literate_integration
___________________________________________________________________
(page generated 2022-01-29 23:00 UTC)