Merge pull request #309 from minrk/stencila

stencila support

.gitignore

@@ -9,6 +9,7 @@ MANIFEST
 
 .DS_Store
 .cache
+.pytest_cache
 .coverage
 htmlcov
 

.travis.yml

@@ -37,6 +37,7 @@ env:
   matrix:
   - REPO_TYPE=conda
   - REPO_TYPE=venv
+  - REPO_TYPE=stencila
   - REPO_TYPE=julia
   - REPO_TYPE=r
   - REPO_TYPE=dockerfile

repo2docker/buildpacks/base.py

@@ -65,9 +65,9 @@ RUN apt-get update && \
 
 EXPOSE 8888
 
-{% if env -%}
-# Almost all environment variables
-{% for item in env -%}
+{% if build_env -%}
+# Environment variables required for build
+{% for item in build_env -%}
 ENV {{item[0]}} {{item[1]}}
 {% endfor -%}
 {% endif -%}
@@ -94,6 +94,14 @@ USER root
 COPY src/ ${HOME}
 RUN chown -R ${NB_USER}:${NB_USER} ${HOME}
 
+{% if env -%}
+# The rest of the environment
+{% for item in env -%}
+ENV {{item[0]}} {{item[1]}}
+{% endfor -%}
+{% endif -%}
+
+
 # Run assemble scripts! These will actually build the specification
 # in the repository into the image.
 {% for sd in assemble_script_directives -%}
@@ -182,6 +190,21 @@ class BuildPack:
             "unzip",
         }
 
+    def get_build_env(self):
+        """
+        Ordered list of environment variables to be set for this image.
+
+        Ordered so that environment variables can use other environment
+        variables in their values.
+
+        Expects tuples, with the first item being the environment variable
+        name and the second item being the value.
+
+        These environment variables will be set prior to build.
+        Use .get_env() to set environment variables after build.
+        """
+        return []
+
     def get_env(self):
         """
         Ordered list of environment variables to be set for this image.
@@ -191,6 +214,8 @@ class BuildPack:
 
         Expects tuples, with the first item being the environment variable
         name and the second item being the value.
+
+        These variables will not be available to build.
         """
         return []
 
@@ -225,6 +250,30 @@ class BuildPack:
         """
         return {}
 
+
+    @property
+    def stencila_manifest_dir(self):
+        """Find the stencila manifest dir if it exists"""
+        if hasattr(self, '_stencila_manifest_dir'):
+            return self._stencila_manifest_dir
+
+        # look for a manifest.xml that suggests stencila could be used
+        # when we find one, stencila should be installed
+        # and set environment variables such that
+        # this file is located at:
+        # ${STENCILA_ARCHIVE_DIR}/${STENCILA_ARCHIVE}/manifest.xml
+
+        self._stencila_manifest_dir = None
+        for root, dirs, files in os.walk("."):
+            if "manifest.xml" in files:
+                self._stencila_manifest_dir = root.split(os.path.sep, 1)[1]
+                self.log.info(
+                    "Found stencila manifest.xml in %s",
+                    self._stencila_manifest_dir,
+                )
+                break
+        return self._stencila_manifest_dir
+
     def get_build_scripts(self):
         """
         Ordered list of shell script snippets to build the base image.
@@ -322,6 +371,7 @@ class BuildPack:
         return t.render(
             packages=sorted(self.get_packages()),
             path=self.get_path(),
+            build_env=self.get_build_env(),
             env=self.get_env(),
             labels=self.get_labels(),
             build_script_directives=build_script_directives,
@@ -388,11 +438,31 @@ class BuildPack:
 
 
 class BaseImage(BuildPack):
-    def get_env(self):
+    def get_build_env(self):
+        """Return env directives required for build"""
         return [
             ("APP_BASE", "/srv")
         ]
 
+    def get_env(self):
+        """Return env directives to be set after build"""
+        env = []
+        if self.stencila_manifest_dir:
+            # manifest_dir is the path containing the manifest.xml
+            # archive_dir is the directory containing archive directories (one level up)
+            # default archive is the name of the directory in the archive_dir
+            # such that
+            # ${STENCILA_ARCHIVE_DIR}/${STENCILA_ARCHIVE}/manifest.xml
+            # exists.
+
+            archive_dir, archive = os.path.split(self.stencila_manifest_dir)
+            env.extend([
+                ("STENCILA_ARCHIVE_DIR", "${HOME}/" + archive_dir),
+                ("STENCILA_ARCHIVE", archive),
+            ])
+        return env
+
+
     def detect(self):
         return True
 
@@ -425,6 +495,22 @@ class BaseImage(BuildPack):
             ))
         except FileNotFoundError:
             pass
+        if self.stencila_manifest_dir:
+            assemble_scripts.extend(
+                [
+                    (
+                        "${NB_USER}",
+                        r"""
+                        ${KERNEL_PYTHON_PREFIX}/bin/pip install --no-cache https://github.com/stencila/py/archive/f6a245fd.tar.gz && \
+                        ${KERNEL_PYTHON_PREFIX}/bin/python -m stencila register && \
+                        ${NB_PYTHON_PREFIX}/bin/pip install --no-cache nbstencilaproxy==0.1.1 && \
+                        jupyter serverextension enable --sys-prefix --py nbstencilaproxy && \
+                        jupyter nbextension install    --sys-prefix --py nbstencilaproxy && \
+                        jupyter nbextension enable     --sys-prefix --py nbstencilaproxy
+                        """,
+                    )
+                ]
+            )
         return assemble_scripts
 
     def get_post_build_scripts(self):

repo2docker/buildpacks/conda/__init__.py

@@ -18,14 +18,14 @@ class CondaBuildPack(BaseImage):
     Uses miniconda since it is more lightweight than Anaconda.
 
     """
-    def get_env(self):
+    def get_build_env(self):
         """Return environment variables to be set.
 
         We set `CONDA_DIR` to the conda install directory and
         the `NB_PYTHON_PREFIX` to the location of the jupyter binary.
 
         """
-        env = super().get_env() + [
+        env = super().get_build_env() + [
             ('CONDA_DIR', '${APP_BASE}/conda'),
             ('NB_PYTHON_PREFIX', '${CONDA_DIR}'),
         ]

repo2docker/buildpacks/julia.py

@@ -12,7 +12,7 @@ class JuliaBuildPack(CondaBuildPack):
     See https://github.com/JuliaPy/PyCall.jl/issues/410
 
     """
-    def get_env(self):
+    def get_build_env(self):
         """Get additional environment settings for Julia and Jupyter
 
         Returns:
@@ -31,7 +31,7 @@ class JuliaBuildPack(CondaBuildPack):
             For example, a tuple may be `('JULIA_VERSION', '0.6.0')`.
 
         """
-        return super().get_env() + [
+        return super().get_build_env() + [
             ('JULIA_PATH', '${APP_BASE}/julia'),
             ('JULIA_HOME', '${JULIA_PATH}/bin'),
             ('JULIA_PKGDIR', '${JULIA_PATH}/pkg'),

repo2docker/buildpacks/r.py

@@ -82,7 +82,7 @@ class RBuildPack(PythonBuildPack):
             '/usr/lib/rstudio-server/bin/'
         ]
 
-    def get_env(self):
+    def get_build_env(self):
         """
         Return environment variables to be set.
 
@@ -90,7 +90,7 @@ class RBuildPack(PythonBuildPack):
         without needing root. This is set via the `R_LIBS_USER` environment
         variable, so we set that here.
         """
-        return super().get_env() + [
+        return super().get_build_env() + [
             # This is the path where user libraries are installed
             ('R_LIBS_USER', '${APP_BASE}/rlibs')
         ]

tests/stencila/basic/archive/py-jupyter/bibliography.bibtex

@@ -0,0 +1,21 @@
+@article{kluyver2016jupyter,
+  title={Jupyter Notebooks-a publishing format for reproducible computational workflows.},
+  author={Kluyver, Thomas and Ragan-Kelley, Benjamin and P{\'e}rez, Fernando and Granger, Brian E and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica B and Grout, Jason and Corlay, Sylvain and others},
+  journal={ELPUB},
+  pages={87--90},
+  year={2016}
+}
+@article{ragan2014jupyter,
+  title={The Jupyter/IPython architecture: a unified view of computational research, from interactive exploration to communication and publication.},
+  author={Ragan-Kelley, M and Perez, F and Granger, B and Kluyver, T and Ivanov, P and Frederic, J and Bussonnier, M},
+  journal={AGU Fall Meeting Abstracts},
+  year={2014}
+}
+@article{perez2015project,
+  title={Project Jupyter: Computational narratives as the engine of collaborative data science},
+  author={Perez, Fernando and Granger, Brian E},
+  journal={Retrieved September},
+  volume={11},
+  pages={207},
+  year={2015}
+}

tests/stencila/basic/archive/py-jupyter/manifest.xml

@@ -0,0 +1,6 @@
+<dar>
+  <documents>
+    <document id="py-jupyter.ipynb" name="py-jupyter.ipynb" type="article" path="py-jupyter.ipynb.jats.xml" src="py-jupyter.ipynb" />
+  </documents>
+  <assets/>
+</dar>

tests/stencila/basic/archive/py-jupyter/py-jupyter.ipynb.jats.xml

@@ -0,0 +1,212 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.1d3 20150301//EN"  "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <front>
+    <article-meta>
+      <title-group>
+        <article-title>Jupyter and Stencila</article-title>
+      </title-group>
+      <contrib-group content-type="author">
+        <contrib contrib-type="person">
+          <name>
+            <surname>Pawlik</surname>
+            <given-names>Aleksandra</given-names>
+          </name>
+        </contrib>
+      </contrib-group>
+      <abstract>
+        <p>An example of a Jupyter notebook converted into a JATS document for editing in Stencila.</p>
+      </abstract>
+    </article-meta>
+  </front>
+
+  <body>
+    <sec id="introduction-1">
+      <title>Introduction</title>
+      <p>Jupyter notebooks (<xref ref-type="bibr" rid="ref-1">1</xref>&#x2013;<xref ref-type="bibr" rid="ref-3">3</xref>) are one of the most popular platforms for doing reproducible research. Stencila supports importing of Jupyter Notebook <monospace>.ipynb</monospace> files. This allows you to work with collegues to refine a document for final publication while still retaining the code cells, and thus reprodubility of your the work. In the future we also plan to support exporting to <monospace>.ipynb</monospace> files.</p>
+    </sec>
+    <sec id="markdown-cells-1">
+      <title>Markdown cells</title>
+      <p>Most standard Markdown should be supported by the importer including inline <monospace>code</monospace>, headings etc (although the Stencila user interface do not currently support rendering of some elements e.g.&#xA0;math and lists).</p>
+    </sec>
+    <sec id="code-cells-1">
+      <title>Code cells</title>
+      <p>Code cells in notebooks are imported without loss. Stencila&#x2019;s user interface currently differs from Jupyter in that code cells are executed on update while you are typing. This produces a very reactive user experience but is inappropriate for more compute intensive, longer running code cells. We are currently working on improving this to allowing users to decide to execute cells explicitly (e.g.&#xA0;using <monospace>Ctrl+Enter</monospace>).</p>
+      <code specific-use="cell"><named-content><alternatives>
+          <code specific-use="source" language="pyjp" executable="yes">import sys
+import time
+&apos;Hello this is Python %s.%s and it is %s&apos; % (sys.version_info[0], sys.version_info[1], time.strftime(&apos;%c&apos;))</code>
+      <code specific-use="output" language="json">{}</code>
+      </alternatives>
+      </named-content>
+      </code>
+      <p>Stencila also support Jupyter code cells that produce plots. The cell below produces a simple plot based on the example from <ext-link ext-link-type="uri" xlink:href="https://matplotlib.org/examples/shapes_and_collections/scatter_demo.html">the Matplotlib website</ext-link>. Try changing the code below (for example, the variable <monospace>N</monospace>).</p>
+      <code specific-use="cell"><named-content><alternatives>
+          <code specific-use="source" language="pyjp" executable="yes">import numpy as np
+import matplotlib.pyplot as plt
+
+N = 50
+N = min(N, 1000) # Prevent generation of too many numbers :)
+x = np.random.rand(N)
+y = np.random.rand(N)
+colors = np.random.rand(N)
+area = np.pi * (15 * np.random.rand(N))**2  # 0 to 15 point radii
+
+plt.scatter(x, y, s=area, c=colors, alpha=0.5)
+plt.show()</code>
+      <code specific-use="output" language="json">{}</code>
+      </alternatives>
+      </named-content>
+      </code>
+      <p>We are currently working on supporting <ext-link ext-link-type="uri" xlink:href="http://ipython.readthedocs.io/en/stable/interactive/magics.html">Jupyter&#x2019;s magic commands</ext-link> in Stencila via a bridge to Jupyter kernels.</p>
+    </sec>
+    <sec id="metadata-1">
+      <title>Metadata</title>
+      <p>To add some metadata about the document (such as authors, title, abstract and so on), In Jupyter, select <monospace>Edit -&gt; Edit Notebook metadata</monospace> from the top menu. Add the title and abstract as JSON strings and authors and organisations metadata as <ext-link ext-link-type="uri" xlink:href="https://www.w3schools.com/js/js_json_arrays.asp">JSON arrays</ext-link>. Author <monospace>affiliation</monospace> identifiers (like <monospace>university-of-earth</monospace> below) must be unique and preferably use only lowercase characters and no spaces.</p>
+      <p>For example,</p>
+      <preformat> &quot;authors&quot;: [
+    {
+      &quot;given-names&quot;: &quot;Your first name goes here&quot;,
+      &quot;surname&quot;: &quot;Your last name goes here&quot;,
+      &quot;email&quot;: &quot;your.email@your-organisation&quot;,
+      &quot;corresponding&quot;: &quot;yes / no&quot;,
+      &quot;affiliation&quot;: &quot;university-of-earth&quot;
+    }
+  ],
+
+  &quot;organisations&quot;: [
+     {
+      &quot;university-of-earth&quot;: {
+        &quot;institution&quot;: &quot;Your organisation name&quot;,
+        &quot;city&quot;: &quot;Your city&quot;,
+        &quot;country&quot;: &quot;Your country&quot;
+      }
+    ],
+
+  &quot;title&quot;: &quot;Your title goes here&quot;,
+  &quot;abstract&quot;: &quot;This is a paper about lots of different interesting things&quot;,
+  </preformat>
+    </sec>
+    <sec id="citations-and-references-1">
+      <title>Citations and references</title>
+      <p>Stencila supports Pandoc style citations and reference lists within Jupyter notebook Markdown cells. Add a <monospace>bibliography</monospace> entry to the notebook&#x2019;s metadata which points to a file containing your list of references e.g.</p>
+      <code language="json">&quot;bibliography&quot;: &quot;my-bibliography.bibtex&quot;</code>
+      <p>Then, within Markdown cells, you can insert citations inside square brackets and separated by semicolons. Each citation is represented using the <monospace>@</monospace> symbol followed by the citation identifier from the bibliography database e.g.</p>
+      <code language="json">[@perez2015project; @kluyver2016jupyter]</code>
+      <p>The <ext-link ext-link-type="uri" xlink:href="https://github.com/takluyver/cite2c">cite2c</ext-link> Jupyter extension allows for easier, &#x201C;cite-while-you-write&#x201D; insertion of citations from a Zotero library. We&#x2019;re hoping to support conversion of cite2cstyle citations/references in the <ext-link ext-link-type="uri" xlink:href="https://github.com/stencila/convert/issues/14">future</ext-link>.</p>
+    </sec>
+  </body>
+  <back>
+    <ref-list>
+      <ref id="ref-1">
+        <element-citation publication-type="journal">
+          <person-group person-group-type="author">
+            <name>
+              <surname>Perez</surname>
+              <given-names>Fernando</given-names>
+            </name>
+            <name>
+              <surname>Granger</surname>
+              <given-names>Brian E</given-names>
+            </name>
+          </person-group>
+          <article-title>Project jupyter: Computational narratives as the engine of collaborative data science</article-title>
+          <source>Retrieved September</source>
+          <year>2015</year>
+          <volume>11</volume>
+          <fpage>207</fpage>
+        </element-citation>
+      </ref>
+      <ref id="ref-2">
+        <element-citation publication-type="journal">
+          <person-group person-group-type="author">
+            <name>
+              <surname>Kluyver</surname>
+              <given-names>Thomas</given-names>
+            </name>
+            <name>
+              <surname>Ragan-Kelley</surname>
+              <given-names>Benjamin</given-names>
+            </name>
+            <name>
+              <surname>P&#xE9;rez</surname>
+              <given-names>Fernando</given-names>
+            </name>
+            <name>
+              <surname>Granger</surname>
+              <given-names>Brian E</given-names>
+            </name>
+            <name>
+              <surname>Bussonnier</surname>
+              <given-names>Matthias</given-names>
+            </name>
+            <name>
+              <surname>Frederic</surname>
+              <given-names>Jonathan</given-names>
+            </name>
+            <name>
+              <surname>Kelley</surname>
+              <given-names>Kyle</given-names>
+            </name>
+            <name>
+              <surname>Hamrick</surname>
+              <given-names>Jessica B</given-names>
+            </name>
+            <name>
+              <surname>Grout</surname>
+              <given-names>Jason</given-names>
+            </name>
+            <name>
+              <surname>Corlay</surname>
+              <given-names>Sylvain</given-names>
+            </name>
+            <name>
+              <surname>Others</surname>
+            </name>
+          </person-group>
+          <article-title>Jupyter notebooks-a publishing format for reproducible computational workflows.</article-title>
+          <source>ELPUB</source>
+          <year>2016</year>
+          <fpage>87</fpage>
+        </element-citation>
+      </ref>
+      <ref id="ref-3">
+        <element-citation publication-type="journal">
+          <person-group person-group-type="author">
+            <name>
+              <surname>Ragan-Kelley</surname>
+              <given-names>M</given-names>
+            </name>
+            <name>
+              <surname>Perez</surname>
+              <given-names>F</given-names>
+            </name>
+            <name>
+              <surname>Granger</surname>
+              <given-names>B</given-names>
+            </name>
+            <name>
+              <surname>Kluyver</surname>
+              <given-names>T</given-names>
+            </name>
+            <name>
+              <surname>Ivanov</surname>
+              <given-names>P</given-names>
+            </name>
+            <name>
+              <surname>Frederic</surname>
+              <given-names>J</given-names>
+            </name>
+            <name>
+              <surname>Bussonnier</surname>
+              <given-names>M</given-names>
+            </name>
+          </person-group>
+          <article-title>The jupyter/ipython architecture: A unified view of computational research, from interactive exploration to communication and publication.</article-title>
+          <source>AGU Fall Meeting Abstracts</source>
+          <year>2014</year>
+        </element-citation>
+      </ref>
+    </ref-list>
+  </back>
+</article>

tests/stencila/basic/archive/r-markdown/bibliography.bibtex

@@ -0,0 +1,13 @@
+@article{baumer2014r,
+  title={R Markdown: Integrating a reproducible analysis tool into introductory statistics},
+  author={Baumer, Ben and Cetinkaya-Rundel, Mine and Bray, Andrew and Loi, Linda and Horton, Nicholas J},
+  journal={arXiv preprint arXiv:1402.1894},
+  year={2014}
+}
+
+@book{xie2016bookdown,
+  title={Bookdown: Authoring Books and Technical Documents with R Markdown},
+  author={Xie, Yihui},
+  year={2016},
+  publisher={CRC Press}
+}

tests/stencila/basic/archive/r-markdown/manifest.xml

@@ -0,0 +1,6 @@
+<dar>
+  <documents>
+    <document id="rmarkdown.Rmd" name="rmarkdown.Rmd" type="article" path="rmarkdown.Rmd.jats.xml" src="rmarkdown.Rmd" />
+  </documents>
+  <assets/>
+</dar>

tests/stencila/basic/archive/r-markdown/rmarkdown.Rmd

@@ -0,0 +1,57 @@
+---
+title: RMarkdown and Stencila
+author:
+  - surname: Bentley
+    given-names: Nokome
+    affiliation: stencila
+  - surname: Pawlik
+    given-names: Aleksandra
+  - surname: Aufrieter
+    given-names: Michael
+    affiliation: substance
+  - surname: Buchtala
+    given-names: Oliver
+    affiliation: substance
+organisations:
+  - id: stencila
+    name: Stencila
+    city: Kaikoura
+    country: New Zealand
+  - id: substance
+    name: Substance GmbH
+    city: Linz
+    country: Austria
+abstract: |
+  Stencila currently supports import of RMarkdown documents. This allows use cases like allowing collaborators to work on the same document using a WYSIWYG editing environment, or for you to put the final touches on a paper before final submission to a journal.
+bibliography: bibliography.bibtex
+---
+
+# Introduction
+
+[RMarkdown](https://rmarkdown.rstudio.com/) is a popular format for reproducible research using the R programming language ([@baumer2014r],[@xie2016bookdown]). Stencila is a able to import RMarkdown documents. For example, the source for this example document is available on [Github](https://github.com/stencila/stencila/blob/more-examples/data/r-markdown/rmarkdown.Rmd). Eventually, we'll also support exporting to RMarkdown, allowing WYSIWYG editing of RMarkdown documents in Stencila.
+
+# Code chunks
+
+In RMarkdown, code "chunks" are written using "fenced" code blocks. Stencila converts these code "chunks" into Stencila code "cells" like this one:
+
+```{r}
+n <- 500
+```
+
+Stencila cells behave like functions having zero or more named `inputs` (like function arguments) and an optional `output` (like a assigning a function's return value). A cell's inputs and outputs are determined by analyzing the cell's code. The cell above has no inputs but produces an output variable named `n`. Stencila's execution engine uses this information to make code cells reactive. For instance, the cell below has `n` as an input i.e it is dependent on the first cell. So when you update the `n` in the cell above, the following plot will update.
+
+```{r}
+s <- min(1000, n)
+x <- runif(s)
+y <- x + runif(s)
+z <- y + rnorm(s)
+plot(x, y, cex=z*2, col=rainbow(length(z), alpha=0.5)[rank(x+z)], pch=16)
+```
+
+# Figures
+
+In RMarkdown, code chunks can have various options. A common use for options is to set the caption and dimensions of figures. Stencila converts code chunks with the `fig.cap` option into JATS `<fig fig-type="repro-fig">` elements with a `<caption>`. This allows the user to edit the figure caption and for automatic figure numbering and referencing (although that is not working 100% right now). Other options are placed in a comment at the top of the cell so that they are preserved (and eventually will be used to apply those options within the R execution context).
+
+```{r fig.width=7,fig.height=6,fig.cap="Figure title"}
+hist(z, breaks=40, col=hsv(0.6, 0.9, 1), xlab="Value", main="")
+```

tests/stencila/basic/archive/r-markdown/rmarkdown.Rmd.jats.xml

@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.1d3 20150301//EN"  "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <front>
+    <article-meta>
+      <title-group>
+        <article-title>RMarkdown and Stencila</article-title>
+      </title-group>
+      <contrib-group content-type="author">
+        <contrib contrib-type="person">
+          <name>
+            <surname>Bentley</surname>
+            <given-names>Nokome</given-names>
+          </name>
+          <xref ref-type="aff" rid="stencila" />
+        </contrib>
+        <contrib contrib-type="person">
+          <name>
+            <surname>Pawlik</surname>
+            <given-names>Aleksandra</given-names>
+          </name>
+        </contrib>
+        <contrib contrib-type="person">
+          <name>
+            <surname>Aufrieter</surname>
+            <given-names>Michael</given-names>
+          </name>
+          <xref ref-type="aff" rid="substance" />
+        </contrib>
+        <contrib contrib-type="person">
+          <name>
+            <surname>Buchtala</surname>
+            <given-names>Oliver</given-names>
+          </name>
+          <xref ref-type="aff" rid="substance" />
+        </contrib>
+      </contrib-group>
+      <aff id="stencila">
+        <institution content-type="orgname">Stencila</institution>
+        <city>Kaikoura</city>
+        <country>New Zealand</country>
+      </aff>
+      <aff id="substance">
+        <institution content-type="orgname">Substance GmbH</institution>
+        <city>Linz</city>
+        <country>Austria</country>
+      </aff>
+      <abstract>
+        <p>Stencila currently supports import of RMarkdown documents. This allows use cases like allowing collaborators to work on the same document using a WYSIWYG editing environment, or for you to put the final touches on a paper before final submission to a journal.</p>
+      </abstract>
+    </article-meta>
+  </front>
+
+  <body>
+    <sec id="introduction-1">
+      <title>Introduction</title>
+      <p><ext-link ext-link-type="uri" xlink:href="https://rmarkdown.rstudio.com/">RMarkdown</ext-link> is a popular format for reproducible research using the R programming language (<xref ref-type="bibr" rid="ref-1">1</xref>,<xref ref-type="bibr" rid="ref-2">2</xref>). Stencila is a able to import RMarkdown documents. For example, the source for this example document is available on <ext-link ext-link-type="uri" xlink:href="https://github.com/stencila/stencila/blob/more-examples/data/r-markdown/rmarkdown.Rmd">Github</ext-link>. Eventually, we&#x2019;ll also support exporting to RMarkdown, allowing WYSIWYG editing of RMarkdown documents in Stencila.</p>
+    </sec>
+    <sec id="code-chunks-1">
+      <title>Code chunks</title>
+      <p>In RMarkdown, code &#x201C;chunks&#x201D; are written using &#x201C;fenced&#x201D; code blocks. Stencila converts these code &#x201C;chunks&#x201D; into Stencila code &#x201C;cells&#x201D; like this one:</p>
+      <code specific-use="cell"><named-content><alternatives>
+          <code specific-use="source" language="r" executable="yes">n &lt;- 500</code>
+      <code specific-use="output" language="json">{}</code>
+      </alternatives>
+      </named-content>
+      </code>
+      <p>Stencila cells behave like functions having zero or more named <monospace>inputs</monospace> (like function arguments) and an optional <monospace>output</monospace> (like a assigning a function&#x2019;s return value). A cell&#x2019;s inputs and outputs are determined by analyzing the cell&#x2019;s code. The cell above has no inputs but produces an output variable named <monospace>n</monospace>. Stencila&#x2019;s execution engine uses this information to make code cells reactive. For instance, the cell below has <monospace>n</monospace> as an input i.e it is dependent on the first cell. So when you update the <monospace>n</monospace> in the cell above, the following plot will update.</p>
+      <code specific-use="cell"><named-content><alternatives>
+          <code specific-use="source" language="r" executable="yes">s &lt;- min(1000, n)
+x &lt;- runif(s)
+y &lt;- x + runif(s)
+z &lt;- y + rnorm(s)
+plot(x, y, cex=z*2, col=rainbow(length(z), alpha=0.5)[rank(x+z)], pch=16)</code>
+      <code specific-use="output" language="json">{}</code>
+      </alternatives>
+      </named-content>
+      </code>
+    </sec>
+    <sec id="figures-1">
+      <title>Figures</title>
+      <p>In RMarkdown, code chunks can have various options. A common use for options is to set the caption and dimensions of figures. Stencila converts code chunks with the <monospace>fig.cap</monospace> option into JATS <monospace>&lt;fig fig-type=&quot;repro-fig&quot;&gt;</monospace> elements with a <monospace>&lt;caption&gt;</monospace>. This allows the user to edit the figure caption and for automatic figure numbering and referencing (although that is not working 100% right now). Other options are placed in a comment at the top of the cell so that they are preserved (and eventually will be used to apply those options within the R execution context).</p>
+      <fig fig-type="repro-fig">
+        <caption>
+          <title>Figure title</title>
+        </caption>
+        <alternatives>
+          <code specific-use="source" language="r" executable="yes">#: fig.width=7,fig.height=6
+hist(z, breaks=40, col=hsv(0.6, 0.9, 1), xlab=&quot;Value&quot;, main=&quot;&quot;)</code>
+          <code specific-use="output" language="json">{}</code>
+        </alternatives>
+      </fig>
+    </sec>
+  </body>
+  <back>
+    <ref-list>
+      <ref id="ref-1">
+        <element-citation publication-type="journal">
+          <person-group person-group-type="author">
+            <name>
+              <surname>Baumer</surname>
+              <given-names>Ben</given-names>
+            </name>
+            <name>
+              <surname>Cetinkaya-Rundel</surname>
+              <given-names>Mine</given-names>
+            </name>
+            <name>
+              <surname>Bray</surname>
+              <given-names>Andrew</given-names>
+            </name>
+            <name>
+              <surname>Loi</surname>
+              <given-names>Linda</given-names>
+            </name>
+            <name>
+              <surname>Horton</surname>
+              <given-names>Nicholas J</given-names>
+            </name>
+          </person-group>
+          <article-title>R markdown: Integrating a reproducible analysis tool into introductory statistics</article-title>
+          <source>arXiv preprint arXiv:1402.1894</source>
+          <year>2014</year>
+        </element-citation>
+      </ref>
+      <ref id="ref-2">
+        <element-citation publication-type="book">
+          <person-group person-group-type="author">
+            <name>
+              <surname>Xie</surname>
+              <given-names>Yihui</given-names>
+            </name>
+          </person-group>
+          <source>Bookdown: Authoring books and technical documents with r markdown</source>
+          <publisher-name>CRC Press</publisher-name>
+          <year>2016</year>
+        </element-citation>
+      </ref>
+    </ref-list>
+  </back>
+</article>

tests/stencila/basic/verify

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+jupyter serverextension list 2>&1 | grep nbstencilaproxy
+jupyter nbextension list 2>&1 | grep nbstencilaproxy