Code output for literate syntaxs

[FiloSottile]

Having literate support for any language is great! But my Python parser will never run that .py.md file.

Would it be possible to offer an option for plain code output? Like --code, that by default creates the corresponding .py, if specified in a folder.

I might be missing something here obviously, but if you think it would be useful I can provide a PR.

[jashkenas]

Nope. You're not missing anything. It would be ideal if Python (and other languages) did support that .py.md file some day ... a boy can dream.

My hesitation on adding something like this is that I'm not quite sure that Docco is the appropriate tool to be generating source files for you. But I could probably be persuaded. A really clean pull request with a nice API would probably help.

[joyrexus]

The marked module makes it relatively easy to extract out code blocks.

codeFrom = (source) ->
  (t.text for t in marked.lexer(source) when t.type == 'code').join "\n"

Demo gist.

Sample usage:

[neocotic]

This would be a great feature addition. I can understand hesitation towards adding this as docco is meant to be a "quick and dirty" code documentation generator but this would just be making docco more powerful and influential in spreading accessibility of literate programming.

Also, I agree that this should be left until a clean API (both via CLI and programmatically) can be presented. I could even see this as being a boost for languages like Java etc. that I would not normally associate with literate programming.

[neocotic]

I've created PR #199 in attempt to implement this functionality. I'd be interested in getting input from all of the participants of this issue.

[joyrexus]

@FiloSottile wrote: "Would it be possible to offer an option for plain code output? Like --code, that by default creates the corresponding .py, if specified in a folder?"

@jashkenas replied: "I'm not quite sure that Docco is the appropriate tool to be generating source files for you."

FWIW ...

While selective extraction of code blocks is handy, extending docco for this purpose feels like feature creep to me.

Also, wherever implemented, instead of writing source files why not send to STDOUT? That way you can redirect to a file if desired OR send to an appropriate interpreter (e.g., extracto my.python.md | python -s).

[Truffula]

In case anyone is interested, Literature seems to meet the needs described here. There is also a gulp plugin. It seems to be language-agnostic, although from what I can tell the CLI outputs to STDOUT (it doesn't output a file for you). If anything it's probably the right place for this functionality though (it essentially does what @joyrexus' gist does as far as I can see, but in a repo).

[joyrexus]

@Truffula: Alternatively, you could just use a simple bash function for this:

# Extract indented code blocks
literature () {
     grep '^    ' $1 | sed 's/^    //'
}

This also makes for a handy mapping in vim filetype plugins, e.g. for a literate python filetype ...

" ,r  run/execute code blocks in file
nmap <LocalLeader>r  :!grep "^    " % \| sed 's/^    //' \| python -<CR>

In other words, unix already provides the tooling for extracting and running indented code blocks.

[Truffula]

Thanks @joyrexus. I think this will do the job in most cases but there are potential instances where markdown comments could be indented four spaces or more (e.g. if you have indented code on a line immediately following a markdown paragraph, and any subsequent such lines until a blank line, AFAIK it is handled as a comment). There is also indenting involved in creating markdown lists and with child lists, which I guess wouldn't be treated as code (although you don't see them so often in code comments). Obviously if it's your own code you can make sure you don't have any indented comment lines, in which case the bash functions are fine! :)

[joyrexus]

Good point re sub-sub-lists. The following is probably safer, though still not going to handle every edge case:

# Extract indented code blocks
literature () {
     grep '^    [a-zA-Z]' $1 | sed 's/^    //'
}