[elviejo]

I didn't downvote but I'll try to explain.

Is the fact that you got the idea exactly backwards: is not about putting comments on your scripts. Is about writing an article, intended to be read by humans, that is also executable.

Imagine it this way: Suppose you are reading a blog post on how to install, configure vagrant and install drupal on it. The article is pretty clear an well written and you enjoy it. And you also know that is correct because every single one of the instructions shown was executed while you were reading the article and every output was given back to you.

That is literate programming, is closer to a jupyter notebook than to 'comments on scripts'.

[osteele]

I’ve started to use Jupyter notebooks, with devop recipes as different sections, for this.

You can keep the notebook in the repo if you do two (or three) things:

1. The scripts read passwords from a key store instead of the notebook source. I wrote a Python package for doing this easily in Python cells; for bash, I just use subcommands.

2. A git pre-commit hook clears the notebook output cells.

3. (Optional) A git pre-commit or pre-push hook searches for text that looks like private credentials.

[ZenoArrow]

> "That is literate programming, is closer to a jupyter notebook than to 'comments on scripts'."

Surely that's a matter of perspective? Imagine you have a text document containing one command and one description of that command. Is this a literate programming document or not?

Furthermore, does the mode change depending on which tool is used to open the source file? For example, if I open a Bash script in a text editor then it's a document, and if I open it in Bash then it's a script, but if I could open it in a tool that allows me to both read and execute the script at my leisure does it then become a literate programming document?

Aside from this, to use your Jupyter notebook example, is it necessary for the results of execution to be captured in-line in order to follow the literate programming methodology?

[jonnycomputer]

Answering questions one doesn't like is better than voting them down.