[Python-modules-commits] [nbsphinx] 01/01: Import nbsphinx_0.2.14+ds.orig.tar.xz
Jerome Benoit
calculus-guest at moszumanska.debian.org
Fri Sep 8 06:19:19 UTC 2017
This is an automated email from the git hooks/post-receive script.
calculus-guest pushed a commit to branch upstream
in repository nbsphinx.
commit f2f2c4afe0a844bbe1298d8891986cce99c22cab
Author: Jerome Benoit <calculus at rezozer.net>
Date: Fri Sep 8 09:31:15 2017 +0400
Import nbsphinx_0.2.14+ds.orig.tar.xz
---
LICENSE | 2 +-
NEWS.rst | 16 ++
PKG-INFO | 6 +-
doc/a-normal-rst-file.rst | 38 -----
doc/allow-errors.ipynb | 2 +-
doc/code-cells.ipynb | 67 +++++++-
doc/conf.py | 11 +-
doc/images/stickfigure.png | Bin 0 -> 1167 bytes
doc/markdown-cells.ipynb | 2 +-
doc/pre-executed.ipynb | 8 +-
doc/subdir/a-notebook-in-a-subdir.ipynb | 8 +
doc/subdir/example.ipynb | 87 +++++++++++
doc/timeout.ipynb | 4 +-
doc/usage.ipynb | 221 +++++++++++++++++++++++----
nbsphinx.py | 261 +++++++++++++++++++++++++-------
setup.py | 11 +-
16 files changed, 606 insertions(+), 138 deletions(-)
diff --git a/LICENSE b/LICENSE
index 8db4a47..383db4c 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2015-2016 Matthias Geier
+Copyright (c) 2015-2017 Matthias Geier
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/NEWS.rst b/NEWS.rst
index 17734f6..14bce0d 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -1,3 +1,19 @@
+Version 0.2.14 (2017-06-09):
+ * Add option ``nbsphinx_kernel_name``
+
+Version 0.2.13 (2017-01-25):
+ * Minor fixes
+
+Version 0.2.12 (2016-12-19):
+ * Basic support for widgets
+ * CSS is now "responsive", some new CSS classes
+
+Version 0.2.11 (2016-11-19):
+ * Minor fixes
+
+Version 0.2.10 (2016-10-16):
+ * Enable JavaScript output cells
+
Version 0.2.9 (2016-07-26):
* Add option ``nbsphinx_prompt_width``
diff --git a/PKG-INFO b/PKG-INFO
index aa07b67..e4aaafa 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,8 +1,8 @@
Metadata-Version: 1.1
Name: nbsphinx
-Version: 0.2.9
+Version: 0.2.14
Summary: Jupyter Notebook Tools for Sphinx
-Home-page: http://nbsphinx.rtfd.org/
+Home-page: http://nbsphinx.rtfd.io/
Author: Matthias Geier
Author-email: Matthias.Geier at gmail.com
License: MIT
@@ -45,9 +45,9 @@ Description: Jupyter Notebook Tools for Sphinx
Keywords: Sphinx,Jupyter,notebook
Platform: any
-Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
+Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
diff --git a/doc/a-normal-rst-file.rst b/doc/a-normal-rst-file.rst
index 2201204..6b6f9fc 100644
--- a/doc/a-normal-rst-file.rst
+++ b/doc/a-normal-rst-file.rst
@@ -39,44 +39,6 @@ These links were created with:
* "``../``" is not allowed, you have to specify the full path even if the
current source file is in a subdirectory!
-Sphinx Directives for Jupyter Notebook Cells
---------------------------------------------
-
-For comparison, this is a "normal" Sphinx code block using ``ipython3``
-syntax highlighting:
-
-.. code-block:: ipython3
-
- %file helloworld.py
- #!/usr/bin/env python3
- print('Hello, world!')
-
-The ``nbsphinx`` extension provides custom directives to show notebook cells:
-
-.. nbinput:: ipython3
- :execution-count: 42
-
- 6 * 7
-
-.. nboutput::
- :execution-count: 42
-
- 42
-
-This was created with
-
-.. code-block:: rst
-
- .. nbinput:: ipython3
- :execution-count: 42
-
- 6 * 7
-
- .. nboutput::
- :execution-count: 42
-
- 42
-
Sphinx Directives for Info/Warning Boxes
----------------------------------------
diff --git a/doc/allow-errors.ipynb b/doc/allow-errors.ipynb
index 6e45ae9..c67c829 100644
--- a/doc/allow-errors.ipynb
+++ b/doc/allow-errors.ipynb
@@ -19,7 +19,7 @@
"\n",
"If a notebook contains errors on purpose (or if you are too lazy to fix them right now), you have three options:\n",
"\n",
- "1. Manually execute the notebook in question and save the results, see [the pre-executed example notebook](pre-executed.ipynb#Exceptions).\n",
+ "1. Manually execute the notebook in question and save the results, see [the pre-executed example notebook](pre-executed.ipynb).\n",
"\n",
"2. Allow errors in all notebooks by setting this option in [conf.py](conf.py):\n",
"```\n",
diff --git a/doc/code-cells.ipynb b/doc/code-cells.ipynb
index b8f2341..5a4de55 100644
--- a/doc/code-cells.ipynb
+++ b/doc/code-cells.ipynb
@@ -150,6 +150,30 @@
"cell_type": "markdown",
"metadata": {},
"source": [
+ "## Cell Magics\n",
+ "\n",
+ "Cells can contain code in other languages by means of [cell magics](http://ipython.readthedocs.io/en/stable/interactive/magics.html#cell-magics):"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": false
+ },
+ "outputs": [],
+ "source": [
+ "%%bash\n",
+ "for i in 1 2 3\n",
+ "do\n",
+ " echo $i\n",
+ "done"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
"## Special Display Formats\n",
"\n",
"See [IPython example notebook](https://nbviewer.jupyter.org/github/ipython/ipython/blob/master/examples/IPython Kernel/Rich Output.ipynb).\n",
@@ -346,6 +370,47 @@
},
{
"cell_type": "markdown",
+ "metadata": {
+ "deletable": true,
+ "editable": true
+ },
+ "source": [
+ "### Arbitrary JavaScript Output (HTML only)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": false,
+ "deletable": true,
+ "editable": true
+ },
+ "outputs": [],
+ "source": [
+ "%%javascript\n",
+ "\n",
+ "var text = document.createTextNode(\"Hello, I was generated with JavaScript!\");\n",
+ "// Content appended to \"element\" will be visible in the output area:\n",
+ "element.appendChild(text);"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "<div class=\"alert alert-info\">\n",
+ "\n",
+ "**Note:**\n",
+ "\n",
+ "jQuery should be available, but using the readthedocs.org default theme, it's not. See [the issue on Github](https://github.com/snide/sphinx_rtd_theme/issues/328).\n",
+ "Other Sphinx themes are not affected by this.\n",
+ "\n",
+ "</div>"
+ ]
+ },
+ {
+ "cell_type": "markdown",
"metadata": {},
"source": [
"### Unsupported Output Types\n",
@@ -489,7 +554,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.5.1+"
+ "version": "3.5.2+"
}
},
"nbformat": 4,
diff --git a/doc/conf.py b/doc/conf.py
index e830713..047dc7b 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,9 +16,15 @@ exclude_patterns = ['_build', '**.ipynb_checkpoints']
# Default language for syntax highlighting in reST and Markdown cells
highlight_language = 'none'
+# Don't add .txt suffix to source files (available for Sphinx >= 1.5):
+html_sourcelink_suffix = ''
+
# Execute notebooks before conversion: 'always', 'never', 'auto' (default)
#nbsphinx_execute = 'never'
+# Use this kernel instead of the one stored in the notebook metadata:
+#nbsphinx_kernel_name = 'python3'
+
# List of arguments to be passed to the kernel that executes the notebooks:
#nbsphinx_execute_arguments = ['--InlineBackend.figure_formats={"png", "pdf"}']
@@ -34,13 +40,16 @@ highlight_language = 'none'
# Width of input/output prompts used in CSS:
#nbsphinx_prompt_width = '8ex'
+# If window is narrower than this, input/output prompts are on separate lines:
+#nbsphinx_responsive_width = '700px'
+
# -- The settings below this line are not specific to nbsphinx ------------
master_doc = 'index'
project = 'nbsphinx'
author = 'Matthias Geier'
-copyright = '2016, ' + author
+copyright = '2017, ' + author
linkcheck_ignore = [r'http://localhost:\d+/']
diff --git a/doc/images/stickfigure.png b/doc/images/stickfigure.png
new file mode 100644
index 0000000..c3310f1
Binary files /dev/null and b/doc/images/stickfigure.png differ
diff --git a/doc/markdown-cells.ipynb b/doc/markdown-cells.ipynb
index ae2ff6c..115ca79 100644
--- a/doc/markdown-cells.ipynb
+++ b/doc/markdown-cells.ipynb
@@ -284,7 +284,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.5.1+"
+ "version": "3.4.4"
}
},
"nbformat": 4,
diff --git a/doc/pre-executed.ipynb b/doc/pre-executed.ipynb
index 2413066..5ba0f1b 100644
--- a/doc/pre-executed.ipynb
+++ b/doc/pre-executed.ipynb
@@ -147,10 +147,10 @@
"evalue": "division by zero",
"output_type": "error",
"traceback": [
- "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
- "\u001b[1;31mZeroDivisionError\u001b[0m Traceback (most recent call last)",
- "\u001b[1;32m<ipython-input-5-b710d87c980c>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m()\u001b[0m\n\u001b[1;32m----> 1\u001b[1;33m \u001b[1;36m1\u001b[0m \u001b[1;33m/\u001b[0m \u001b[1;36m0\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
- "\u001b[1;31mZeroDivisionError\u001b[0m: division by zero"
+ "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+ "\u001b[0;31mZeroDivisionError\u001b[0m Traceback (most recent call last)",
+ "\u001b[0;32m<ipython-input-5-b710d87c980c>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;36m1\u001b[0m \u001b[0;34m/\u001b[0m \u001b[0;36m0\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
+ "\u001b[0;31mZeroDivisionError\u001b[0m: division by zero"
]
}
],
diff --git a/doc/subdir/a-notebook-in-a-subdir.ipynb b/doc/subdir/a-notebook-in-a-subdir.ipynb
index 84027d5..bb8912f 100644
--- a/doc/subdir/a-notebook-in-a-subdir.ipynb
+++ b/doc/subdir/a-notebook-in-a-subdir.ipynb
@@ -36,6 +36,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
+ "<div class=\"alert alert-warning\">\n",
+ "\n",
+ "**Warning:**\n",
+ "\n",
+ "There may be problems with images in output cells if your source directory contains symbolic links, see [issue #49](https://github.com/spatialaudio/nbsphinx/issues/49).\n",
+ "\n",
+ "</div>\n",
+ "\n",
"A link to a notebook in the parent directory: [link](../markdown-cells.ipynb).\n",
"\n",
"A link to a local file: [link](../images/notebook_icon.png).\n",
diff --git a/doc/subdir/example.ipynb b/doc/subdir/example.ipynb
new file mode 100644
index 0000000..f387e50
--- /dev/null
+++ b/doc/subdir/example.ipynb
@@ -0,0 +1,87 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# TEMS Tutorial: Data Download using MATLAB\n",
+ "* **How do I download TEMS data?**"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "* Check if get_tems_data method is in search path."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": false
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "/var/matlab/ifog_analysis/get_tems_data.m\n"
+ ]
+ }
+ ],
+ "source": [
+ "% check if get_tems_data method is in search path\n",
+ "which get_tems_data"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "\n",
+ "- Help information of get_tems_data."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "get_tems_data?"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "* Get some data."
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Matlab",
+ "language": "matlab",
+ "name": "matlab"
+ },
+ "language_info": {
+ "codemirror_mode": "octave",
+ "file_extension": ".m",
+ "help_links": [
+ {
+ "text": "MetaKernel Magics",
+ "url": "https://github.com/calysto/metakernel/blob/master/metakernel/magics/README.md"
+ }
+ ],
+ "mimetype": "text/x-matlab",
+ "name": "matlab",
+ "version": "0.13.0+3.g1ab53e8"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/doc/timeout.ipynb b/doc/timeout.ipynb
index f6f8085..ec32e9c 100644
--- a/doc/timeout.ipynb
+++ b/doc/timeout.ipynb
@@ -28,10 +28,10 @@
"```json\n",
"\"nbsphinx\": {\n",
" \"timeout\": 60\n",
- "}\n",
+ "},\n",
"```\n",
"\n",
- "Alternatively, you can manually execute the notebook in question and save the results, see [the pre-executed example notebook](pre-executed.ipynb#Long-Running-Cells)."
+ "Alternatively, you can manually execute the notebook in question and save the results, see [the pre-executed example notebook](pre-executed.ipynb)."
]
}
],
diff --git a/doc/usage.ipynb b/doc/usage.ipynb
index bff0970..ccb994d 100644
--- a/doc/usage.ipynb
+++ b/doc/usage.ipynb
@@ -17,17 +17,81 @@
"\n",
"## Installation\n",
"\n",
+ "### nbsphinx\n",
+ "\n",
"Install `nbsphinx` with `pip`:\n",
"\n",
" python3 -m pip install nbsphinx --user\n",
"\n",
+ "If you want to install it system-wide for all users (assuming you have the necessary rights), just drop the `--user` flag.\n",
+ "\n",
"If you suddenly change your mind, you can un-install it with:\n",
"\n",
" python3 -m pip uninstall nbsphinx\n",
"\n",
"Depending on your Python installation, you may have to use `python` instead of `python3`.\n",
"Recent versions of Python already come with `pip` pre-installed.\n",
- "If you don't have it, you can [install it manually](https://pip.pypa.io/en/latest/installing/)."
+ "If you don't have it, you can [install it manually](https://pip.pypa.io/en/latest/installing/).\n",
+ "\n",
+ "To upgrade to the newest release, use the `--upgrade` flag:\n",
+ "\n",
+ " python3 -m pip install nbsphinx --upgrade --user\n",
+ "\n",
+ "If you don't want to use `pip`, you can also try to install `nbsphinx` with your package manager.\n",
+ "For example, there is a [package for conda-forge](https://anaconda.org/conda-forge/nbsphinx)\n",
+ "and packages for\n",
+ "[Debian](https://packages.debian.org/search?keywords=nbsphinx),\n",
+ "[Ubuntu](http://packages.ubuntu.com/search?keywords=nbsphinx), [Arch](https://aur.archlinux.org/packages/python-nbsphinx/)\n",
+ "and [Gentoo](https://packages.gentoo.org/packages/dev-python/nbsphinx) Linux.\n",
+ "Note that those might not provide the latest releases.\n",
+ "\n",
+ "### pandoc\n",
+ "\n",
+ "The stand-alone program [pandoc](http://pandoc.org/) is used to convert Markdown content to something Sphinx can understand. You have to install this program separately, ideally with your package manager. If you are using `conda`, you can select the [conda-forge](https://conda-forge.github.io/) channel to install the [pandoc](https://anaconda.org/conda-forge/pandoc) package.\n",
+ "If that doesn't work out for you, have a look at `pandoc`'s [installation instructions](http://pandoc.org/installing.html).\n",
+ "\n",
+ "<div class=\"alert alert-info\">\n",
+ "\n",
+ "**Note:**\n",
+ "\n",
+ "The use of `pandoc` in `nbsphinx` is temporary, but will likely stay that way for a long time, see [issue #36](https://github.com/spatialaudio/nbsphinx/issues/36).\n",
+ "\n",
+ "</div>\n",
+ "\n",
+ "### Syntax Highlighting\n",
+ "\n",
+ "To get proper syntax highlighting in code cells, you'll need an appropriate *Pygments lexer*.\n",
+ "This of course depends on the programming language of your Jupyter notebooks (more specifically, the `pygments_lexer` metadata of your notebooks).\n",
+ "\n",
+ "For example, if you use Python in your notebooks, you'll have to have the `IPython` package installed:\n",
+ "\n",
+ " python3 -m pip install IPython --user\n",
+ "\n",
+ "You'll most likely have this installed already.\n",
+ "\n",
+ "\n",
+ "<div class=\"alert alert-info\">\n",
+ "\n",
+ "**Note:**\n",
+ "\n",
+ "If you are using Anaconda and syntax highlighting in code cells doesn't seem to work,\n",
+ "you can try to install IPython with `pip`, or as a work-around,\n",
+ "add `'IPython.sphinxext.ipython_console_highlighting'` to `extensions` in my `conf.py`.\n",
+ "\n",
+ "For details, see [Anaconda issue #1430](https://github.com/ContinuumIO/anaconda-issues/issues/1430) and\n",
+ "[nbsphinx issue #24](https://github.com/spatialaudio/nbsphinx/issues/24).\n",
+ "\n",
+ "</div>\n",
+ "\n",
+ "### Jupyter Kernel\n",
+ "\n",
+ "If you want to execute your notebooks during the Sphinx build process (see [Executing Notebooks](executing-notebooks.ipynb)), you need an appropriate [Jupyter kernel](http://jupyter.readthedocs.io/en/latest/projects/kernels.html) installed.\n",
+ "\n",
+ "For example, if you use Python, you should install the `ipykernel` package:\n",
+ "\n",
+ " python3 -m pip install ipykernel --user\n",
+ "\n",
+ "Again, it's very likely that you have that installed already."
]
},
{
@@ -53,7 +117,20 @@
"exclude_patterns = ['_build', '**.ipynb_checkpoints']\n",
"```\n",
"\n",
- "Once your `conf.py` is in place, edit the file named `index.rst` and add the file names of your notebooks (with or without the `.ipynb` extension) to the [toctree](http://www.sphinx-doc.org/en/stable/markup/toctree.html) directive."
+ "Once your `conf.py` is in place, edit the file named `index.rst` and add the file names of your notebooks (with or without the `.ipynb` extension) to the [toctree](http://www.sphinx-doc.org/en/stable/markup/toctree.html) directive.\n",
+ "\n",
+ "<div class=\"alert alert-info\">\n",
+ "\n",
+ "**autosummary bug:**\n",
+ "\n",
+ "If you are using the `sphinx.ext.autosummary` Sphinx extension, there is [a bug in Sphinx (below version 1.5)](https://github.com/sphinx-doc/sphinx/issues/2485) which prevents notebooks from being parsed. \n",
+ "As a work-around you can explicitly list all the files for which autosummary should be ran using the [autosummary_generate](http://www.sphinx-doc.org/en/stable/ext/autosummary.html#confval-autosummary_generate) variable in `conf.py`. For example,\n",
+ "\n",
+ "```python\n",
+ "autosummary_generate = ['myfile1.rst', 'myfile2.rst']\n",
+ "```\n",
+ "\n",
+ "</div>"
]
},
{
@@ -130,28 +207,100 @@
"source": [
"## Automatic Creation of HTML and PDF output on [readthedocs.org](https://readthedocs.org)\n",
"\n",
- "This is very easy!\n",
+ "There are two different methods, both of which are described below.\n",
+ "\n",
+ "In both cases, you'll first have to create an account on https://readthedocs.org/ and connect your Github/Bitbucket account. Instead of connecting, you can also manually add any publicly available Git/Subversion/Mercurial/Bazaar repository.\n",
+ "\n",
+ "After doing the steps described below, you only have to \"push\" to your repository, and the HTML pages and the PDF file of your stuff are automagically created on readthedocs.org. Awesome!\n",
+ "\n",
+ "You can even have different versions of your stuff, just use Git tags and branches and select in the readthedocs.org settings (under \"Admin\", \"Versions\") which of those should be created.\n",
"\n",
- "1. Create an account on https://readthedocs.org/ and add your Github/Bitbucket repository (or any publicly available Git/Subversion/Mercurial/Bazaar repository).\n",
+ "If your new versions are not automatically built, go to the “Settings” of your Github repository, continue to “Integrations & services”, and make sure that “ReadTheDocs” is listed and activated in the “Services” section. If not, use “Add service”. There is probably a similar thing for Bitbucket and others.\n",
"\n",
- "1. Create a file named [requirements.txt](requirements.txt) (or whatever name you wish) in your repository containing the required pip packages:\n",
+ "<div class=\"alert alert-info\">\n",
+ "\n",
+ "**Note:**\n",
+ "\n",
+ "If you want to execute notebooks (see [Controlling Notebook Execution](executing-notebooks.ipynb)), you'll need to install the appropriate Jupyter kernel. In the examples below, the IPython kernel ist installed from the packet `ipykernel`.\n",
+ "\n",
+ "</div>"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Using `requirements.txt`\n",
+ "\n",
+ "1. Create a file named `requirements.txt` (or whatever name you wish) in your repository containing the required pip packages:\n",
"\n",
" sphinx>=1.4\n",
- " nbsphinx\n",
" ipykernel\n",
+ " nbsphinx\n",
+ " \n",
+ " You can also install directly from Github et al., using a specific branch/tag/commit, e.g.\n",
+ "\n",
+ " git+https://github.com/spatialaudio/nbsphinx.git@master\n",
"\n",
- "1. In the \"Advanced Settings\" on readthedocs.org, specify the path to your `requirements.txt` file (or however you called it) in the box labelled \"Requirements file\". Kinda obvious, isn't it?\n",
+ "1. In the \"Advanced Settings\" on readthedocs.org, specify the path to your `requirements.txt` file (or however you called it) in the box labeled \"Requirements file\". Kinda obvious, isn't it?\n",
"\n",
- "1. Still in the \"Advanced Settings\", make sure the right Python interpreter is chosen. This must be the same version (2.x or 3.x) as you were using in your notebooks!\n",
+ "1. Still in the \"Advanced Settings\", make sure the right Python interpreter is chosen. This must be the same version (2.x or 3.x) as you were using in your notebooks!"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Using `conda`\n",
"\n",
- "1. Make sure that in the \"Settings\" of your Github repository, under \"Webhooks & services\", \"ReadTheDocs\" is listed and activated in the \"Services\" section. If not, use \"Add service\".\n",
- " There is probably a similar thing for Bitbucket.\n",
+ "1. Create a file named `readthedocs.yml` in the main directory of your repository, containing the name of yet another file:\n",
"\n",
- "1. Done!\n",
+ " conda:\n",
+ " file: readthedocs-environment.yml\n",
"\n",
- "After that, you only have to \"push\" to your repository, and the HTML pages and the PDF file of your stuff are automagically created on readthedocs.org. Awesome!\n",
+ "1. Create the file mentioned above.\n",
+ "You can choose whatever name you want (it may also live in a subdirectory, e.g. `doc/environment.yml`), it just has to match whatever is specified in `readthedocs.yml`.\n",
+ "The second file describes a [conda environment](http://conda.pydata.org/docs/using/envs.html) and should contain something like this:\n",
"\n",
- "You can even have different versions of your stuff, just use Git tags and branches and select in the readthedocs.org settings (under \"Admin\", \"Versions\") which of those should be created."
+ " channels:\n",
+ " - conda-forge\n",
+ " dependencies:\n",
+ " - python==3.5\n",
+ " - sphinx>=1.4\n",
+ " - pandoc\n",
+ " - nbconvert\n",
+ " - ipykernel\n",
+ " - pip:\n",
+ " - nbsphinx\n",
+ "\n",
+ " You can of course add further `conda` and `pip` packages. You can also install packages directly from Github et al., using a specific branch/tag/commit, e.g.\n",
+ " \n",
+ " - pip:\n",
+ " - git+https://github.com/spatialaudio/nbsphinx.git@master\n",
+ "\n",
+ "<div class=\"alert alert-info\">\n",
+ "\n",
+ "**Note:**\n",
+ "\n",
+ "The specification of the `conda-forge` channel is necessary for the `pandoc` package, which is not part of the default channel.\n",
+ "\n",
+ "</div>\n",
+ "\n",
+ "<div class=\"alert alert-info\">\n",
+ "\n",
+ "**Note:**\n",
+ "\n",
+ "Most of the \"Advanced Settings\" on readthedocs.org will be ignored if you have a `readthedocs.yml` file.\n",
+ "\n",
+ "</div>\n",
+ "\n",
+ "<div class=\"alert alert-warning\">\n",
+ "\n",
+ "**Warning:**\n",
+ "\n",
+ "If you have a very long repository name (or branch name), you might run into this quite obscure problem: ['placeholder too short'](https://github.com/rtfd/readthedocs.org/issues/1902).\n",
+ "\n",
+ "</div>"
]
},
{
@@ -162,11 +311,15 @@
"\n",
"The `nbsphinx` extension does *not* provide its own theme, you can use any of the available themes or [create a custom one](http://www.sphinx-doc.org/en/stable/theming.html#creating-themes), if you feel like it.\n",
"\n",
- "The following links show how the `nbsphinx` documentation looks like in different themes.\n",
+ "The following (incomplete) list of themes contains several links for each theme:\n",
+ "\n",
+ "1. The documentation (or the official sample page) of this theme (if available, see also the [documentation of the built-in Sphinx themes](http://www.sphinx-doc.org/en/latest/theming.html#builtin-themes))\n",
+ "1. How the `nbsphinx` documentation looks when using this theme\n",
+ "1. How to enable this theme using either `requirements.txt` or `readthedocs.yml` and theme-specific settings (in some cases)\n",
"\n",
"### Sphinx's Built-In Themes\n",
"\n",
- "* `alabaster`:\n",
+ "* [alabaster](https://alabaster.readthedocs.io/):\n",
" [example](http://nbsphinx.readthedocs.io/en/alabaster-theme/),\n",
" [usage](https://github.com/spatialaudio/nbsphinx/compare/alabaster-theme^...alabaster-theme)\n",
"\n",
@@ -200,30 +353,46 @@
"\n",
"### 3rd-Party Themes\n",
"\n",
- "* `sphinx_rtd_theme`:\n",
- " [example](http://nbsphinx.readthedocs.io/en/readthedocs-theme/),\n",
- " [usage](https://github.com/spatialaudio/nbsphinx/compare/readthedocs-theme^...readthedocs-theme)\n",
+ "* [sphinx_rtd_theme](https://github.com/snide/sphinx_rtd_theme):\n",
+ " [example](http://nbsphinx.readthedocs.io/en/rtd-theme/),\n",
+ " [usage](https://github.com/spatialaudio/nbsphinx/compare/rtd-theme^...rtd-theme)\n",
"\n",
- "* `bootstrap`:\n",
+ "* [bootstrap](http://sphinx-bootstrap-theme.readthedocs.io/):\n",
" [example](http://nbsphinx.readthedocs.io/en/bootstrap-theme/),\n",
" [usage](https://github.com/spatialaudio/nbsphinx/compare/bootstrap-theme^...bootstrap-theme)\n",
"\n",
- "* `cloud`, `redcloud`:\n",
+ "* [cloud](https://pythonhosted.org/cloud_sptheme/):\n",
" [example](http://nbsphinx.readthedocs.io/en/cloud-theme/),\n",
" [usage](https://github.com/spatialaudio/nbsphinx/compare/cloud-theme^...cloud-theme)\n",
"\n",
- "* `sphinx_py3doc_enhanced_theme`:\n",
- " [example](http://nbsphinx.readthedocs.io/en/py3doc-enhanced-theme/),\n",
- " [usage](https://github.com/spatialaudio/nbsphinx/compare/py3doc-enhanced-theme^...py3doc-enhanced-theme)\n",
+ "* [sphinx_py3doc_enhanced_theme](https://github.com/ionelmc/sphinx-py3doc-enhanced-theme):\n",
+ " [example](http://nbsphinx.readthedocs.io/en/py3doc-enh-theme/),\n",
+ " [usage](https://github.com/spatialaudio/nbsphinx/compare/py3doc-enh-theme^...py3doc-enh-theme)\n",
"\n",
- "* `basicstrap`:\n",
+ "* [basicstrap](http://pythonhosted.org/sphinxjp.themes.basicstrap/):\n",
" [example](http://nbsphinx.readthedocs.io/en/basicstrap-theme/),\n",
" [usage](https://github.com/spatialaudio/nbsphinx/compare/basicstrap-theme^...basicstrap-theme)\n",
"\n",
- "* `dotted`:\n",
+ "* [dotted](https://pythonhosted.org/sphinxjp.themes.dotted/):\n",
" [example](http://nbsphinx.readthedocs.io/en/dotted-theme/),\n",
" [usage](https://github.com/spatialaudio/nbsphinx/compare/dotted-theme^...dotted-theme)\n",
"\n",
+ "* [better](https://sphinx-better-theme.readthedocs.io/):\n",
+ " [example](http://nbsphinx.readthedocs.io/en/better-theme/),\n",
+ " [usage](https://github.com/spatialaudio/nbsphinx/compare/better-theme^...better-theme)\n",
+ "\n",
+ "* [guzzle_sphinx_theme](https://github.com/guzzle/guzzle_sphinx_theme):\n",
+ " [example](http://nbsphinx.readthedocs.io/en/guzzle-theme/),\n",
+ " [usage](https://github.com/spatialaudio/nbsphinx/compare/guzzle-theme^...guzzle-theme)\n",
+ "\n",
+ "* [julia](https://github.com/JuliaLang/JuliaDoc):\n",
+ " [example](http://nbsphinx.readthedocs.io/en/julia-theme/),\n",
+ " [usage](https://github.com/spatialaudio/nbsphinx/compare/julia-theme^...julia-theme)\n",
+ "\n",
+ "* [jupyter](https://github.com/jupyter/jupyter-sphinx-theme/):\n",
+ " [example](http://nbsphinx.readthedocs.io/en/jupyter-theme/),\n",
+ " [usage](https://github.com/spatialaudio/nbsphinx/compare/jupyter-theme^...jupyter-theme)\n",
+ "\n",
"If you know of another Sphinx theme that should be included here, please open an [issue on Github](https://github.com/spatialaudio/nbsphinx/issues)."
]
}
@@ -244,7 +413,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.5.1+"
+ "version": "3.5.2+"
}
},
"nbformat": 4,
diff --git a/nbsphinx.py b/nbsphinx.py
index f96006b..86525f7 100644
--- a/nbsphinx.py
+++ b/nbsphinx.py
@@ -1,4 +1,4 @@
-# Copyright (c) 2015-2016 Matthias Geier
+# Copyright (c) 2015-2017 Matthias Geier
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
@@ -23,29 +23,34 @@
http://nbsphinx.rtfd.org/
"""
-__version__ = '0.2.9'
+__version__ = '0.2.14'
import copy
-import docutils
-from docutils.parsers import rst
-import jinja2
import json
-import nbconvert
-import nbformat
import os
import re
-import sphinx
import subprocess
try:
from urllib.parse import unquote # Python 3.x
except ImportError:
from urllib2 import unquote # Python 2.x
+import docutils
+from docutils.parsers import rst
+import jinja2
+import nbconvert
+import nbformat
+import sphinx
+import sphinx.errors
+import traitlets
+
_ipynbversion = 4
# See nbconvert/exporters/html.py:
DISPLAY_DATA_PRIORITY_HTML = (
'application/javascript',
+ 'application/vnd.jupyter.widget-view+json',
+ 'application/vnd.jupyter.widget-state+json',
'text/html',
'text/markdown',
'image/svg+xml',
@@ -88,8 +93,10 @@ RST_TEMPLATE = """
{% block input -%}
-.. nbinput:: {% if nb.metadata.language_info -%}
-{{ nb.metadata.language_info.pygments_lexer }}
+.. nbinput:: {% if cell.metadata.magics_language -%}
+{{ cell.metadata.magics_language }}
+{%- elif nb.metadata.language_info -%}
+{{ nb.metadata.language_info.pygments_lexer or nb.metadata.language_info.name }}
{%- else -%}
{{ resources.codecell_lexer }}
{%- endif -%}
@@ -134,13 +141,29 @@ RST_TEMPLATE = """
{%- elif datatype in ['text/latex'] %}
.. math::
+ :nowrap:
-{{ output.data['text/latex'] | strip_dollars | indent | indent }}
+{{ output.data['text/latex'] | indent | indent }}
{%- elif datatype == 'text/html' %}
.. raw:: html
{{ output.data['text/html'] | indent | indent }}
+{%- elif datatype == 'application/javascript' %}
+{% set div_id = uuid4() %}
+
+ .. raw:: html
+
+ <div id="{{ div_id }}"></div>
+ <script type="text/javascript">
+ var element = document.getElementById('{{ div_id }}');
+{{ output.data['application/javascript'] | indent | indent }}
+ </script>
+{%- elif datatype.startswith('application') and datatype.endswith('+json') %}
+
+ .. raw:: html
+
+ <script type="{{ datatype }}">{{ output.data[datatype] | json_dumps }}</script>
{%- elif datatype == 'ansi' %}
.. rst-class:: highlight
@@ -153,10 +176,14 @@ RST_TEMPLATE = """
.. raw:: latex
- % This comment is needed to force a line break for adjacent ANSI cells
+ %
\\begin{OriginalVerbatim}[commandchars=\\\\\\{\\}]
{{ output.data[datatype] | ansi2latex | indent | indent }}
\\end{OriginalVerbatim}
+ % The following \\relax is needed to avoid problems with adjacent ANSI
+ % cells and some other stuff (e.g. bullet lists) following ANSI cells.
+ % See https://github.com/sphinx-doc/sphinx/issues/3594
+ \\relax
{% else %}
.. nbwarning:: Data type cannot be displayed: {{ datatype }}
@@ -203,6 +230,7 @@ RST_TEMPLATE = """
.. raw:: latex
+ %
{{ cell.source | indent }}
{%- elif raw_mimetype == 'text/html' %}
.. raw:: html
@@ -211,6 +239,7 @@ RST_TEMPLATE = """
{%- elif raw_mimetype == 'text/latex' %}
.. raw:: latex
+ %
{{ cell.source | indent }}
{%- elif raw_mimetype == 'text/markdown' %}
{{ cell.source | markdown2rst }}
@@ -218,6 +247,20 @@ RST_TEMPLATE = """
{{ cell.source }}
{% endif %}
{% endblock rawcell %}
+
+
+{% block footer %}
+
+{% if 'application/vnd.jupyter.widget-state+json' in nb.metadata.widgets %}
+
+.. raw:: html
+
+ <script type="application/vnd.jupyter.widget-state+json">
+ {{ nb.metadata.widgets['application/vnd.jupyter.widget-state+json'] | json_dumps }}
+ </script>
+{% endif %}
+{{ super() }}
+{% endblock footer %}
"""
@@ -250,13 +293,15 @@ CSS_STRING = """
/* remove conflicting styling from Sphinx themes */
div.nbinput,
-div.nbinput > div,
-div.nbinput div[class^=highlight],
-div.nbinput div[class^=highlight] pre,
+div.nbinput div.prompt,
+div.nbinput div.input_area,
+div.nbinput div[class*=highlight],
+div.nbinput div[class*=highlight] pre,
div.nboutput,
-div.nboutput > div,
-div.nboutput div[class^=highlight],
-div.nboutput div[class^=highlight] pre {
+div.nbinput div.prompt,
+div.nbinput div.output_area,
+div.nboutput div[class*=highlight],
+div.nboutput div[class*=highlight] pre {
background: none;
border: none;
padding: 0 0;
@@ -265,7 +310,7 @@ div.nboutput div[class^=highlight] pre {
}
/* avoid gaps between output lines */
-div.nboutput div[class^=highlight] pre {
+div.nboutput div[class*=highlight] pre {
line-height: normal;
}
@@ -276,6 +321,13 @@ div.nboutput {
display: flex;
align-items: flex-start;
margin: 0;
+ width: 100%%;
+}
+ at media (max-width: %(nbsphinx_responsive_width)s) {
+ div.nbinput,
+ div.nboutput {
+ flex-direction: column;
+ }
}
/* input container */
@@ -289,38 +341,58 @@ div.nblast {
}
/* input prompt */
-div.nbinput > :first-child pre {
+div.nbinput div.prompt pre {
color: #303F9F;
}
/* output prompt */
-div.nboutput > :first-child pre {
+div.nboutput div.prompt pre {
color: #D84315;
}
/* all prompts */
-div.nbinput > :first-child[class^=highlight],
-div.nboutput > :first-child[class^=highlight],
-div.nboutput > :first-child {
+div.nbinput div.prompt,
+div.nboutput div.prompt {
min-width: %(nbsphinx_prompt_width)s;
padding-top: 0.4em;
padding-right: 0.4em;
text-align: right;
flex: 0;
}
+ at media (max-width: %(nbsphinx_responsive_width)s) {
+ div.nbinput div.prompt,
+ div.nboutput div.prompt {
+ text-align: left;
+ padding: 0.4em;
+ }
+ div.nboutput div.prompt.empty {
+ padding: 0;
+ }
+}
+
+/* disable scrollbars on prompts */
+div.nbinput div.prompt pre,
+div.nboutput div.prompt pre {
+ overflow: hidden;
+}
/* input/output area */
-div.nbinput > :nth-child(2)[class^=highlight],
-div.nboutput > :nth-child(2),
-div.nboutput > :nth-child(2)[class^=highlight] {
+div.nbinput div.input_area,
+div.nboutput div.output_area {
padding: 0.4em;
-webkit-flex: 1;
flex: 1;
overflow: auto;
}
+ at media (max-width: %(nbsphinx_responsive_width)s) {
+ div.nbinput div.input_area,
+ div.nboutput div.output_area {
+ width: 100%%;
... 398 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/nbsphinx.git
More information about the Python-modules-commits
mailing list