5 ms·

Writing Literate API Documentation in Emacs Org Mode

105 points by joseph8th 5y ago

thewakalix 5y ago
It would probably be better to remove "Wow" from the title.
- joseph8th 5y ago
  But then what would I do with all this extra hyperbole?
  - laerus 5y ago
    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 5y ago
      Sorry! Fixed the links. Thanks for point it out. It was WOMMing.
- dang 5y ago
  OK, we've dewowed the title above.
buscoquadnary 5y ago
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 5y ago
  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.
  - JNRowe 5y ago
    Not OP, but… They're not in the same league, although this isn't a knock on fugitive as they have different goals. If you don't want to try magit¹ itself, then vimagit² is a reasonable approximation within vim. It gives you the same kind of workflow as magit, but doesn't quite feel as polished IME. ¹ You don't need to be an emacs user to use magit, you can treat magit as a standalone application. ² https://github.com/jreybert/vimagit https://github.com/jreybert/vimagit
- joseph8th 5y ago
  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.
- fire 5y ago
  These are exactly the types of things I wish I could get myself to spend the time to learn, but unless I can force myself to learn something as an actual part of building somethings that interests me, I'll never actually pick it up :(
  - schaefer 5y ago
    Okay. In this case, the thing you’d be building is the documentation (and your own expertise). Does that interest you???
    - fire 5y ago
      I actually don't hate writing docs to help other people, but can rarely motivate myself to write them for my own consumption, heh
kristjansson 5y ago
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 5y ago
  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.
moeris 5y ago
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 https://github.com/savantgroup/literate_integration
nesarkvechnep 5y ago
I wouldn't call this an example of literate programming. At least not Knuth's LP.
- mullr 5y ago
  Yeah, it's really not. You CAN do knuth-style literate programming in org-mode (https://orgmode.org/manual/Extracting-Source-Code.html https://orgmode.org/manual/Extracting-Source-Code.html) I used it to make http://mullr.github.io/micrologic/literate.html http://mullr.github.io/micrologic/literate.html. The experience completely cured me of Knuth-style literate programming, fwiw. It's really great for making a lasting artifact about a program that's completely done. But I can count the number of programs I've worked on like that on zero fingers. Even this one isn't really done, but the cost of updating the essay along with the code discouraged me from working on it any more.
  - nesarkvechnep 5y ago
    I’ve experimented with NOWEB in the past and it’s cool. I would imagine it being good for teaching. Like “these are the steps we have to take to accomplish the desired result” and then break down every step with the ability to actually build the code at the end.
  - ParetoOptimal 5y ago
    > It's really great for making a lasting artifact about a program that's completely done. My emacs configuration is the exact opposite of a program that's completely done, but I find literate programming good for managing it's complexity. > The experience completely cured me of Knuth-style literate programming, fwiw. If it's not too much to ask, do you mind sharing some of the pain points?
    - mullr 5y ago
      > If it's not too much to ask, do you mind sharing some of the pain points? To me, the point of literate programming is that you have a coherent (literate, if you well) document that explains how the program actually works, and the reason it's put together how it is. This is NOT an easy thing to write. It takes as much organization as the program itself. I found the document structure to be continuously in flux, as I updated the program to deal with new requirements. So either document would poorly structured, or I would spend a LOT of time keeping it good.
elviejo 5y ago
I love literate programming. But it requires 3 skillets: writing well, programming well and a little DevOps in order to automate the execution of the literate program. So it is actually very difficult to do... But the results are Worth it to have software you can understand forever
JonahSussman 5y ago
From everything I've seen, Org Mode is basically everything that I've ever wanted in a productivity/note-taking app. The only problem is that I would have to use Emacs... I know Org Mode is extremely tied in to Emacs' core, but if someone could figure out how to separate it into a vscode extension or something, that'd be really cool
- medo-bear 5y ago
  lol just get a pdf cheat-sheet for common commands and learn emacs! it is really not that big of a deal. i think you need few hours before you can start using it effectively and independently. ignore the hype. it is just a tool
- ParetoOptimal 5y ago
  That'd be difficult since org isn't super well defined, though there is an orgdown project that aims to fix that by having levels of compatibility. You don't need much emacs for org-mode, especially if you keep the (admittedly dated) context-sensitve toolbar. Here's a cool (but short) infographic that gives you more than enough to go off of: https://sachachua.com/blog/2013/05/how-to-learn-emacs-a-hand-drawn-one-pager-for-beginners/ https://sachachua.com/blog/2013/05/how-to-learn-emacs-a-hand...
golem14 5y ago
This looks great! I don't know how to properly version documentation, and how to prevent accidentally documenting responses for the wrong version number. Any recommendations? Maybe including API version in the response so errors of that kind become very obvious ?
- joseph8th 5y ago
  Good question. In my case, I use the Org file instead of Postman (or some other API client) and I keep it in the same repo with the code. When I generate the `index.html` from Org, I point it at my local API, so there is never any doubt they are on the same version.

105 points by joseph8th 5y ago

thewakalix 5y ago

It would probably be better to remove "Wow" from the title.

joseph8th 5y ago
But then what would I do with all this extra hyperbole?
- laerus 5y ago
  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 5y ago
    Sorry! Fixed the links. Thanks for point it out. It was WOMMing.
dang 5y ago
OK, we've dewowed the title above.

buscoquadnary 5y ago

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 5y ago
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.
- JNRowe 5y ago
  Not OP, but… They're not in the same league, although this isn't a knock on fugitive as they have different goals. If you don't want to try magit¹ itself, then vimagit² is a reasonable approximation within vim. It gives you the same kind of workflow as magit, but doesn't quite feel as polished IME. ¹ You don't need to be an emacs user to use magit, you can treat magit as a standalone application. ² https://github.com/jreybert/vimagit https://github.com/jreybert/vimagit
joseph8th 5y ago
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.
fire 5y ago
These are exactly the types of things I wish I could get myself to spend the time to learn, but unless I can force myself to learn something as an actual part of building somethings that interests me, I'll never actually pick it up :(
- schaefer 5y ago
  Okay. In this case, the thing you’d be building is the documentation (and your own expertise). Does that interest you???
  - fire 5y ago
    I actually don't hate writing docs to help other people, but can rarely motivate myself to write them for my own consumption, heh

kristjansson 5y ago

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 5y ago
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.

moeris 5y ago

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 https://github.com/savantgroup/literate_integration

nesarkvechnep 5y ago

I wouldn't call this an example of literate programming. At least not Knuth's LP.

mullr 5y ago
Yeah, it's really not. You CAN do knuth-style literate programming in org-mode (https://orgmode.org/manual/Extracting-Source-Code.html https://orgmode.org/manual/Extracting-Source-Code.html) I used it to make http://mullr.github.io/micrologic/literate.html http://mullr.github.io/micrologic/literate.html. The experience completely cured me of Knuth-style literate programming, fwiw. It's really great for making a lasting artifact about a program that's completely done. But I can count the number of programs I've worked on like that on zero fingers. Even this one isn't really done, but the cost of updating the essay along with the code discouraged me from working on it any more.
- nesarkvechnep 5y ago
  I’ve experimented with NOWEB in the past and it’s cool. I would imagine it being good for teaching. Like “these are the steps we have to take to accomplish the desired result” and then break down every step with the ability to actually build the code at the end.
- ParetoOptimal 5y ago
  > It's really great for making a lasting artifact about a program that's completely done. My emacs configuration is the exact opposite of a program that's completely done, but I find literate programming good for managing it's complexity. > The experience completely cured me of Knuth-style literate programming, fwiw. If it's not too much to ask, do you mind sharing some of the pain points?
  - mullr 5y ago
    > If it's not too much to ask, do you mind sharing some of the pain points? To me, the point of literate programming is that you have a coherent (literate, if you well) document that explains how the program actually works, and the reason it's put together how it is. This is NOT an easy thing to write. It takes as much organization as the program itself. I found the document structure to be continuously in flux, as I updated the program to deal with new requirements. So either document would poorly structured, or I would spend a LOT of time keeping it good.

elviejo 5y ago

I love literate programming. But it requires 3 skillets: writing well, programming well and a little DevOps in order to automate the execution of the literate program. So it is actually very difficult to do... But the results are Worth it to have software you can understand forever

JonahSussman 5y ago

From everything I've seen, Org Mode is basically everything that I've ever wanted in a productivity/note-taking app. The only problem is that I would have to use Emacs... I know Org Mode is extremely tied in to Emacs' core, but if someone could figure out how to separate it into a vscode extension or something, that'd be really cool

medo-bear 5y ago
lol just get a pdf cheat-sheet for common commands and learn emacs! it is really not that big of a deal. i think you need few hours before you can start using it effectively and independently. ignore the hype. it is just a tool
ParetoOptimal 5y ago
That'd be difficult since org isn't super well defined, though there is an orgdown project that aims to fix that by having levels of compatibility. You don't need much emacs for org-mode, especially if you keep the (admittedly dated) context-sensitve toolbar. Here's a cool (but short) infographic that gives you more than enough to go off of: https://sachachua.com/blog/2013/05/how-to-learn-emacs-a-hand-drawn-one-pager-for-beginners/ https://sachachua.com/blog/2013/05/how-to-learn-emacs-a-hand...

golem14 5y ago

This looks great! I don't know how to properly version documentation, and how to prevent accidentally documenting responses for the wrong version number. Any recommendations? Maybe including API version in the response so errors of that kind become very obvious ?

joseph8th 5y ago
Good question. In my case, I use the Org file instead of Postman (or some other API client) and I keep it in the same repo with the code. When I generate the `index.html` from Org, I point it at my local API, so there is never any doubt they are on the same version.