1. 9
  1.  

  2. 4

    I made something like this for generating tutorials from documentation (though no editing, and more focused on shell commands) https://github.com/schneems/rundoc.

    1. 3

      Very cool, I like the screenshot feature!

      Seems like we have a few common primitives, such as “commands” and “file operations”. We did an empirical study on executability of software tutorials, where we looked at how often these types of things came up and the impact on execution. Paper should be interesting to check out:

      http://chrisparnin.me/pdf/docable_FSE_20.pdf

      1. 2

        Just got back to my replies. Awesome paper, great work. I’ll have to check out your additional command types I like the uncomment idea.

        If I had more time the one thing I’ve never done is to put this somewhere to run totally automated. I generate some of the Heroku docs via rundoc. I’ve always wanted them triggered by releases in Rails versions, but haven’t had the time to wire it up. Right now I just manually run the files.

      2. 2

        This looks like exactly what I was looking for. The biggest feature it has over docable(the OP) for me, is it can be run standalone, i.e. as part of a CI/CD pipeline, etc and doesn’t require some process running somewhere.

        This in some sense even beats emacs org mode’s literate programming as getting the org files ran and publishable outside of emacs is usually a giant pita.

        OP: compatibility between the 2 syntax’s might be nice.

        1. 1

          Yes, the standalone version for what you’re talking about is here (but not as polished)—this is what we use for CI, etc: https://github.com/ottomatica/docable

          This also works on external documentation, by using selectors… this is how we tested the 600+ tutorials.

      3. 2

        Hi Chris, what is the process for adding support for new languages?

        1. 2

          To execute a code block as a script, would mainly require inserting plumping to make sure to call the right interpreter/compiler. For example, you can see an example with node.js code snippets here: https://docable.cloud/chrisparnin/examples/basics/script.md. Adding more languages, would be straightforward, but we were mainly waiting for interest in this feature before going too crazy.

          Our use cases have been mainly for building interactive runbooks we use for simple deployments and operation tasks, and supporting workshop material for our university courses, so we’ve been largely working with tools and shells.

          Finally, since the file blocks could work with any code snippet, technically, you could just make any content you want, and run the necessary command to run it, though in some cases, running a snippet directly might be a better experience.

          ```go | {type:'file', path:'sendmessage.go'}
          // Run `go get golang.org/x/sys/windows`
          package main
          
          import (
          	"fmt"
          	"unsafe"
          	"golang.org/x/sys/windows"
          )
          
          var (
              user32DLL	= windows.NewLazyDLL("user32.dll")
              SendMessageTimeout	= user32DLL.NewProc("SendMessageTimeoutW")
              SendMessage	= user32DLL.NewProc("SendMessageW")
          )
          func main() {
          	text, _ := windows.UTF16PtrFromString("Environment");
          	SendMessage.Call(0xffff, 26, 0, uintptr(unsafe.Pointer(text)) );
          }
          ```
          
          ```bash | {type: 'command'}
          go run sendmessage.go
          ```