Enable "data-cite" HTML tags in Markdown cells

Fixes #22.

Author: mgeier

doc/a-normal-rst-file.rst

@@ -163,3 +163,55 @@ Domain Objects
     :ref:`this section </markdown-cells.ipynb#Links-to-Domain-Objects>`.
 
     :param str foo: Example string parameter
+
+Citations
+---------
+
+You could use `standard Sphinx citations`_, but it might be more practical to
+use the sphinxcontrib.bibtex_ extension.
+
+If you install and enable this extension,
+you can create citations like :cite:`perez2011python`:
+
+.. code-block:: rst
+
+    :cite:`perez2011python`
+
+You can create similar citations in Jupyter notebooks with a special HTML
+syntax, see the section about `citations in Markdown cells`_.
+
+.. _standard Sphinx Citations: https://www.sphinx-doc.org/en/master/usage/
+    restructuredtext/basics.html#citations
+.. _sphinxcontrib.bibtex: https://sphinxcontrib-bibtex.readthedocs.io/
+.. _citations in Markdown cells: markdown-cells.ipynb#Citations
+
+For those citations to work, you also need to specify a BibTeX file,
+as explained in the next section.
+
+
+References
+----------
+
+After installing and enabling the sphinxcontrib.bibtex_ extension,
+you can create a list of references from a BibTeX file like this:
+
+.. code-block:: rst
+
+    .. bibliography:: references.bib
+
+Have a look at the documentation for all the available options.
+
+The list of references may look something like this:
+
+.. bibliography:: references.bib
+    :all:
+    :style: alpha
+
+However, in the LaTeX/PDF output the list of references will not appear here,
+but at the end of the document.
+For a possible work-around,
+see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156.
+
+There is an alternative Sphinx extension for creating bibliographies:
+https://bitbucket.org/wnielson/sphinx-natbib/.
+However, this project seems to be abandoned (last commit in 2011).

doc/conf.py

@@ -100,7 +100,7 @@
     'TeX': {'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True}},
 }
 
-# TODO: explain!
+# Additional files needed for generating LaTeX/PDF output:
 latex_additional_files = ['references.bib']
 
 # -- The settings below this line are not specific to nbsphinx ------------

doc/markdown-cells.ipynb

@@ -153,6 +153,36 @@
     "The above equation has the number \\ref{pythagoras}."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Citations\n",
+    "\n",
+    "According to https://nbconvert.readthedocs.io/en/latest/latex_citations.html,\n",
+    "`nbconvert` supports citations using a special HTML-based syntax.\n",
+    "`nbsphinx` supports the same syntax.\n",
+    "\n",
+    "Example: <cite data-cite=\"kluyver2016jupyter\">Kluyver et al. (2016)</cite>.\n",
+    "\n",
+    "```html\n",
+    "<cite data-cite=\"kluyver2016jupyter\">Kluyver et al. (2016)</cite>\n",
+    "```\n",
+    "\n",
+    "You don't actually have to use `<cite>`,\n",
+    "any inline HTML tag can be used, e.g. `<strong>`:\n",
+    "<strong data-cite=\"perez2011python\">Python: An Ecosystem for Scientific Computing</strong>.\n",
+    "\n",
+    "```html\n",
+    "<strong data-cite=\"perez2011python\">Python: An Ecosystem for Scientific Computing</strong>\n",
+    "```\n",
+    "\n",
+    "You'll also have to define a list of references,\n",
+    "see [the section about references](a-normal-rst-file.rst#references).\n",
+    "\n",
+    "There is also a Notebook extension which may or may not be useful: https://github.com/takluyver/cite2c."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -459,7 +489,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.7"
+   "version": "3.7.1"
   }
  },
  "nbformat": 4,

doc/references.bib

@@ -0,0 +1,21 @@
+@article{perez2011python,
+author = {Pérez, Fernando and Granger, Brian E. and Hunter, John D.},
+title = {Python: An Ecosystem for Scientific Computing},
+journal = {Computing in Science Engineering},
+volume = 13,
+number = 2,
+pages = {13--21},
+doi = {10.1109/MCSE.2010.119},
+year = 2011,
+}
+
+@incollection{kluyver2016jupyter,
+author = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and {Jupyter Development Team}},
+title = {{Jupyter Notebooks}---a publishing format for reproducible computational workflows},
+booktitle = {Positioning and Power in Academic Publishing: Players, Agents and Agendas},
+pages = {87--90},
+publisher = {IOS Press},
+doi = {10.3233/978-1-61499-649-1-87},
+editor = {Loizides, Fernando and Schmidt, Birgit},
+year = 2016,
+}

src/nbsphinx.py

@@ -32,8 +32,10 @@
 import subprocess
 try:
     from urllib.parse import unquote  # Python 3.x
+    from html.parser import HTMLParser
 except ImportError:
     from urllib2 import unquote  # Python 2.x
+    from HTMLParser import HTMLParser
 
 import docutils
 from docutils.parsers import rst
@@ -1017,6 +1019,32 @@ def convert_pandoc(text, from_format, to_format):
     return markdown2rst(text)
 
 
+class CitationParser(HTMLParser):
+
+    def handle_starttag(self, tag, attrs):
+        if self._check_cite(attrs):
+            self.starttag = tag
+
+    def handle_endtag(self, tag):
+        self.endtag = tag
+
+    def handle_startendtag(self, tag, attrs):
+        self._check_cite(attrs)
+
+    def _check_cite(self, attrs):
+        for name, value in attrs:
+            if name == 'data-cite':
+                self.cite = ':cite:`' + value + '`'
+                return True
+        return False
+
+    def reset(self):
+        HTMLParser.reset(self)
+        self.starttag = ''
+        self.endtag = ''
+        self.cite = ''
+
+
 def markdown2rst(text):
     """Convert a Markdown string to reST via pandoc.
 
@@ -1041,16 +1069,38 @@ def displaymath(text):
             ]
         }
 
-    def rawlatex2math_hook(obj):
+    def parse_html(obj):
+        p = CitationParser()
+        p.feed(obj['c'][1])
+        p.close()
+        return p
+
+    open_cite_tag = ''
+
+    def object_hook(obj):
+        nonlocal open_cite_tag
+        if open_cite_tag:
+            if obj.get('t') == 'RawInline' and obj['c'][0] == 'html':
+                p = parse_html(obj)
+                if p.endtag == open_cite_tag:
+                    open_cite_tag = ''
+            return {'t': 'Str', 'c': ''}  # Object is replaced by empty string
+
         if obj.get('t') == 'RawBlock' and obj['c'][0] == 'latex':
             obj['t'] = 'Para'
             obj['c'] = [displaymath(obj['c'][1])]
         elif obj.get('t') == 'RawInline' and obj['c'][0] == 'tex':
             obj = displaymath(obj['c'][1])
+        elif obj.get('t') == 'RawInline' and obj['c'][0] == 'html':
+            p = parse_html(obj)
+            if p.starttag:
+                open_cite_tag = p.starttag
+            if p.cite:
+                obj = {'t': 'RawInline', 'c': ['rst', p.cite]}
         return obj
 
-    def rawlatex2math(text):
-        json_data = json.loads(text, object_hook=rawlatex2math_hook)
+    def filter_func(text):
+        json_data = json.loads(text, object_hook=object_hook)
         return json.dumps(json_data)
 
     input_format = 'markdown'
@@ -1059,7 +1109,7 @@ def rawlatex2math(text):
     if nbconvert.utils.version.check_version(v, '1.13'):
         input_format += '-native_divs+raw_html'
 
-    rststring = pandoc(text, input_format, 'rst', filter_func=rawlatex2math)
+    rststring = pandoc(text, input_format, 'rst', filter_func=filter_func)
     return re.sub(r'^\n( *)\x0e:nowrap:\x0f$',
                   r'\1:nowrap:',
                   rststring,