Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: Encapsulate Markdown Cell in Sphinx directive #45

Closed
wants to merge 9 commits into from
Next Next commit
ENH: add nbsphinx-directive to cell-metadata to wrap markdown cell in…
… sphinx-directive
kmuehlbauer committed Apr 21, 2016

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
commit 72e44d0962348f801796c48096e5ee71476b82ad
31 changes: 30 additions & 1 deletion doc/markdown-cells.ipynb
Original file line number Diff line number Diff line change
@@ -172,9 +172,38 @@
"The linked files are automatically copied to the HTML output directory.\n",
"For LaTeX output, no link is created."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Encapsulate Cell in Sphinx Directive\n",
"\n",
"To facilitate the use of Sphinx Directives, like admonitions (eg. ``.. warning::``), with processed markdown inside a specific metadata switch is added to the cells metadata:\n",
"\n",
"```\n",
"{\n",
" \"nbsphinx-directive\": \"true\"\n",
"}\n",
"```\n",
"\n",
"The first line of the cell must contain the admonition type. It also has to be underlined to give the correct notion within the notebook. Below the output of such a cell is shown"
]
},
{
"cell_type": "markdown",
"metadata": {
"nbsphinx-directive": "true"
},
"source": [
"Warning\n",
"-------\n",
"Also normal markdown like math $\\text{e}^{i\\pi} = -1$, [links to somewhere](#Links-to-Other-Notebooks) or *emphasis*, **boldface** and `preformatted text` can be used within this cell."
]
}
],
"metadata": {
"celltoolbar": "Edit Metadata",
"kernelspec": {
"display_name": "Python 3",
"language": "python",
@@ -190,7 +219,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.5.1+"
"version": "3.5.1"
}
},
"nbformat": 4,
23 changes: 23 additions & 0 deletions nbsphinx.py
Original file line number Diff line number Diff line change
@@ -162,8 +162,12 @@
{%- if 'nbsphinx-toctree' in cell.metadata %}
{{ cell | extract_toctree }}
{%- else %}
{%- if 'nbsphinx-directive' in cell.metadata %}
{{ cell | wrap_cell}}
{%- else %}
{{ super() }}
{% endif %}
{% endif %}
{% endblock markdowncell %}
@@ -375,6 +379,7 @@ def __init__(self, allow_errors=False, timeout=30, codecell_lexer='none'):
'markdown2rst': markdown2rst,
'get_empty_lines': _get_empty_lines,
'extract_toctree': _extract_toctree,
'wrap_cell': _wrap_cell,
})

def from_notebook_node(self, nb, resources=None, **kw):
@@ -667,6 +672,24 @@ def _extract_toctree(cell):
return '\n '.join(lines)


def _wrap_cell(cell):
"""Wrap cell content from Markdown cell in sphinx directive."""
text = cell.source.split('\n', 2)

if len(text) > 2:
admon = text[0]
text = text[2]
else:
admon = 'note'
text = text[0]

text = nbconvert.filters.markdown2rst(text)
text = "".join([".. ", admon.lower(), "::\n\n\t",
text.replace("\n", ' '), "\n"])

return text


def _get_empty_lines(text):
"""Get number of empty lines before and after code."""
before = len(text) - len(text.lstrip('\n'))