[thaumaturgy]

I've seen a few posts here recently on literate programming; I really hope it takes hold as a trend.

A couple of months ago I released a "literate devops" tool: https://github.com/robsheldon/golem/

It extends https://github.com/bashup/mdsh so that you can execute shell code, embedded in markdown, on remote servers. I hope someday that documented server management becomes the standard.

[bshimmin]

It won't ever take off because it's not universally applicable - no one wants to write a CRUD web app as a literate program, for example. Most developers don't want to write any more words than they really have to: just try getting your average developer to write some actual documentation - it's a struggle! (Of course there are some developers who want to write books - but it's a tiny, tiny minority.)

Literate programming will remain an interesting and fun little niche, but I don't think it'll ever get any further than that: it's destined always to be a bit of an academic exercise. (Just so I don't sound like a terribly negative cynic, I have written a couple of literate programs and really enjoyed it.)

[akavel]

Please show a "hello world" script in your readme demonstrating the core feature of your tool. I skimmed the whole big readme and couldn't find any example of an actual literate script. Nor could I find any "examples" dir in the repo.

[thaumaturgy]

An "examples" directory is a great idea that didn't occur to me at all.

Do you have a suggestion for a useful example that would be better than the example at the top of the readme?

[akavel]

I don't see any markdown in the script at the top, it looks like a normal bash script. It doesn't look in any way as "literate programming" as commonly understood since originally introduced. I'm in utterly confused how this example script is in any way related to what we're talking about in this thread, including your post above.

[thaumaturgy]

I wasn't snarking. Writing one or more markdown-specific examples is something I'd like to do. I was asking for ideas for examples that would be more useful to sysadmins than the shell example at the top of the readme.

[akavel]

No problem, I just assumed some kind of misunderstanding and tried to explain my thoughts in different words :) I'm afraid I don't have especially great ideas for that, nor am I a sysadmin. In fact, I was hoping to see some example of how you'd suggest to use the thing so that I would better understand it and get inspired :P hm, dunno, how about uploading my ssh public key to a remote machine? Just random idea of a thing commonly needed to be done.

[wizzwizz4]

Isn't this an examples directory? https://github.com/zyedidia/Literate/tree/master/examples

[e12e]

I like the idea, but I think I'd prefer to go more towards mdsh - I already write up markdown documents for various tasks - I would prefer extracting and running code directly from file (eg: a local checkout of a gitlab wiki project, or from a docs-folder in a checkout of a regular project).

Maybe I can bend mdsh to my needs with a bit of inspiration from your project.

Currently there's expected to be a bit of copy paste from the wiki/rendered markdown - but that only scales so far. (I generally do drop helper scripts in a project /bin folder, and document the use of those via markdown - but having a sensible way to execute code blocks would maybe help).

Ed: Or perhaps I'm better off just using https://zyedidia.github.io/literate/index.html directly.

[thaumaturgy]

I started with "just use mdsh", but then found that executing mdsh scripts on remote servers was yucky; either the file needed to be copied up, executed, and then cleaned up, or the file was executed over ssh but that was fragile. It took a lot of tries to find a way to do it that didn't break bash or sudo or interactive prompts from remote programs.

I used that trick for a while, but it required the `--compile` option for mdsh, and re-compiling each script every time was silly. Also, I wanted shellcheck to look at the output each time to make sure something wasn't horribly broken before running some markdown on a server. (Other than the part where I'm running markdown on a remote server.)

So, I started caching the compiled files. Then I wanted a couple of convenience functions added to them. Then golem sort of happened.

It pretty much just takes mdsh and makes it safer and nicer to run on remotes.

[e12e]

Right. My use case is more to tweak and test a few scripts, then have a(nother| junior) dev(op) be able to clone a repo and set up a service or server.

Maybe with some minor obvious tweaks.

I've looked at ansible - but I'm not convinced that it's a good fit; ansible feels a bit like a padded straight jacket, rather than comfortable outwear, so to speak.

I need to weaponize my documentation, rather than dull the edge of my shell recepies ;)

[brudgers]

I first heard of Literate DevOps via this video a few years ago https://youtu.be/dljNabciEGg