Is there documentation explaining the "magic" markup needed to include R/Python code in markdown documents?


#1

Hi, I heard about Stencila at the C4RR (containers for reproducible research) conference in Cambridge (UK) earlier in the week. It looked really impressive. The talk mentioned bringing together “clickers”, “scripters” and “coders”. I’m in the “scripter/coder” camp. Currently it seems like the documentation is mainly aimed at the “clickers”. For someone like me it would be great to see some examples of the “magic” markup needed to include R/Python code in a markup document, the command(s) needed to compile my text document to PDF, and how to point the desktop tool at my text document. In other words documentation from the point of view of the person writing text in Vim, who later on wants to share the document with a “clicker”. Is this type of documentation available anywhere?


#2

Hi @tjelvar-olsson,

Thanks for your interest and the questions!

You’re right we don’t have any good documentation for those things. Partly that’s because our Markdown extensions are evolving. Partly it’s because we haven’t got around to it yet! One of the things on my to do list for next week is to write some “Stencila for RMarkdown users”, “Stencila for Jupyter users”,… etc docs. But in the meantime, I’ll try to answer your questions here.

Markdown extensions

some examples of the “magic” markup needed to include R/Python code in a markup document

Stencila documents have the concepts of inputs, cells and outputs. For each of these we define a markdown extension. See https://github.com/stencila/examples/blob/master/diamonds/README.md for examples of all of these.

Cells

To insert a code cell into a document use a fenced codeblock with either the run or call function (the difference between these is explained in the docs) and the language in curly braces e.g.

 ```run(){r}
 plot(x,y)
 ```

When using call you can pass and return variables e.g.

 ```result=call(var1,var2){py}
 return var1 * var2
 ```

Personally, I’m not happy with this syntax but it’s what is currently in v0.26. I’ll create another post with some proposed changes (comments welcome!)

Inputs

We use Pandoc’s bracketed_spans extension (although we don’t actually use Pandoc) for inputs. At the moment, only range slider inputs are supported (more coming soon):

 [0.2]{name=smoothing type=range min=0.1 max=1 step=0.1}

where 0.2 is the default value and name is the name of the variable which will be defined.

Outputs

For output’s we also intend to use bracketed_spans but right now that hasn’t been implemented so you have to treat them as “inline cells” by using an inline HTML span in your Markdown.

<span data-cell="pseudo_r2"><span>

Open a document

how to point the desktop tool at my text document

In the desktop app go to the File > Open menu item and select your *.md file. It should then appear in the list of documents in the desktop.

‘Save as’ a document

the command(s) needed to compile my text document to PDF

I’m afraid that’s not possible in the desktop right now. In v0.27 we will add a ‘Save as’ (or ‘Export’) menu item.

If you’d really like to save to a PDF right now, it’s possible by opening the document at http://open.stenci.la and using the web browsers ‘Print to PDF’. Let me know if you’d like to do that and I can give you some instructions.

Hope that helps,

Nokome


#3

Hi @tjelvar-olsson,

Just wondering if you had a chance to try this out? Don’t hesitate to let me know if you have any more questions.

BTW. We made changes to the Markdown format in the recent 0.27 release - see https://raw.githubusercontent.com/stencila/examples/master/diamonds/README.md for an example.


#4

Hi @nokome,

I did play around with it a little bit. However, I did get stuck on the difference between “run” and “call”.

It took me some time to work out that the documentation was part of the Stencila Desktop application. These days I am so used to documentation being made available as a web page. If the same documentation is available on-line it may be worth sticking in a hyperlink to it in the answer.

When I was reading the documentation explaining the difference between “run” and “call” I found it difficult to understand why these two concepts were needed. I guess I am used to IPython notebooks where everything just behaves as if it is one big Python script with comments. Perhaps it would be an idea of adding a section to the documentation explaining why the two concepts are needed and following this with some “real life” examples of when one should use one over the other.

Note that the feedback above is probably mainly a reflection of the fact that I am busy and don’t have masses of time playing around with things, so if I don’t get it immediately I drift off to other things that need my attention.

Tjelvar


#5

Thanks @tjelvar-olsson for the great feedback.

It took me some time to work out that the documentation was part of the Stencila Desktop application. These days I am so used to documentation being made available as a web page. If the same documentation is available on-line it may be worth sticking in a hyperlink to it in the answer.

Yes, I totally agree that we need to make the documentation available standalone online. It’s something that is on the to do list.

When I was reading the documentation explaining the difference between “run” and “call” I found it difficult to understand why these two concepts were needed. I guess I am used to IPython notebooks where everything just behaves as if it is one big Python script with comments. Perhaps it would be an idea of adding a section to the documentation explaining why the two concepts are needed and following this with some “real life” examples of when one should use one over the other.

Thanks, that’s a good suggestion.

In the 0.27 release we changed the syntax for external code cells to try and make the difference easier to understand. Cells executed within a local scope (i.e. call cells) are now the default and instead of using a separate language input field, each language has “function alias” e.g. here is a cell of R code with a single input:

If you want a semantic that is closer to IPython/Jupyter notebook then you add the new global keyword e.g.

One possible feature addition is to allow the user to specify that they want all cells to default to global py() (ie. something like a Python Notebook) or global r() (i.e. something like a RMarkdown document).

Notwithstanding all of that, as you say, we need to explain better in the documentation why the two concepts are needed and some compelling use cases.

Note that the feedback above is probably mainly a reflection of the fact that I am busy and don’t have masses of time playing around with things, so if I don’t get it immediately I drift off to other things that need my attention.

I think this is exactly the same situation that most potential users of Stencila will be in! If there are too many barriers to “getting it” they will just give up and stick with tools they already know or those that have fewer barriers to entry. So you feedback is really valuable! :slight_smile: