[Python-modules-commits] [nbconvert] 02/11: Import nbconvert_5.1.1.orig.tar.gz
Gordon Ball
chronitis-guest at moszumanska.debian.org
Fri Jan 27 19:25:05 UTC 2017
This is an automated email from the git hooks/post-receive script.
chronitis-guest pushed a commit to branch master
in repository nbconvert.
commit 77ac5d9046b9e679b3d5107b19d4f2139b6a1262
Author: Gordon Ball <gordon at chronitis.net>
Date: Thu Jan 26 12:58:10 2017 +0100
Import nbconvert_5.1.1.orig.tar.gz
---
docs/src/ipykernel/.gitignore => .gitignore | 9 +-
docs/src/ipykernel/.mailmap => .mailmap | 0
.travis.yml | 42 +
CONTRIBUTING.md | 2 +-
docs/src/ipykernel/MANIFEST.in => MANIFEST.in | 0
PKG-INFO | 21 -
README.md | 14 +-
codecov.yml | 10 +
docs/README.md | 31 +-
docs/autogen_config.py | 2 +-
docs/environment.yml | 13 +-
docs/source/api/exporters.rst | 36 +-
docs/source/api/filters.rst | 4 +-
docs/source/architecture.rst | 65 +-
docs/source/changelog.rst | 48 +
docs/source/conf.py | 6 +-
docs/source/customizing.ipynb | 20 +-
docs/source/execute_api.rst | 4 +-
docs/source/external_exporters.rst | 27 +-
docs/source/install.rst | 49 +-
docs/source/latex_citations.rst | 2 +-
docs/source/nbconvert_library.ipynb | 28 +-
docs/source/template_structure.html | 18 +-
docs/source/usage.rst | 10 +
docs/src/ipykernel/.travis.yml | 17 -
docs/src/ipykernel/CONTRIBUTING.md | 3 -
docs/src/ipykernel/COPYING.md | 59 -
docs/src/ipykernel/README.md | 11 -
docs/src/ipykernel/docs/Makefile | 192 -
docs/src/ipykernel/docs/changelog.rst | 58 -
docs/src/ipykernel/docs/conf.py | 303 -
docs/src/ipykernel/docs/index.rst | 23 -
docs/src/ipykernel/docs/make.bat | 263 -
.../examples/embedding/inprocess_qtconsole.py | 46 -
.../examples/embedding/inprocess_terminal.py | 31 -
.../examples/embedding/internal_ipkernel.py | 55 -
.../ipykernel/examples/embedding/ipkernel_qtapp.py | 75 -
.../ipykernel/examples/embedding/ipkernel_wxapp.py | 119 -
docs/src/ipykernel/ipykernel.egg-info/PKG-INFO | 21 -
docs/src/ipykernel/ipykernel.egg-info/SOURCES.txt | 73 -
.../ipykernel.egg-info/dependency_links.txt | 1 -
docs/src/ipykernel/ipykernel.egg-info/requires.txt | 7 -
.../src/ipykernel/ipykernel.egg-info/top_level.txt | 1 -
docs/src/ipykernel/ipykernel/__init__.py | 2 -
docs/src/ipykernel/ipykernel/__main__.py | 3 -
docs/src/ipykernel/ipykernel/_version.py | 5 -
docs/src/ipykernel/ipykernel/codeutil.py | 35 -
docs/src/ipykernel/ipykernel/comm/__init__.py | 2 -
docs/src/ipykernel/ipykernel/comm/comm.py | 169 -
docs/src/ipykernel/ipykernel/comm/manager.py | 158 -
docs/src/ipykernel/ipykernel/connect.py | 180 -
docs/src/ipykernel/ipykernel/datapub.py | 57 -
docs/src/ipykernel/ipykernel/displayhook.py | 72 -
docs/src/ipykernel/ipykernel/embed.py | 57 -
docs/src/ipykernel/ipykernel/eventloops.py | 273 -
docs/src/ipykernel/ipykernel/gui/__init__.py | 15 -
docs/src/ipykernel/ipykernel/gui/gtk3embed.py | 85 -
docs/src/ipykernel/ipykernel/gui/gtkembed.py | 86 -
docs/src/ipykernel/ipykernel/heartbeat.py | 68 -
docs/src/ipykernel/ipykernel/inprocess/__init__.py | 8 -
docs/src/ipykernel/ipykernel/inprocess/blocking.py | 93 -
docs/src/ipykernel/ipykernel/inprocess/channels.py | 97 -
docs/src/ipykernel/ipykernel/inprocess/client.py | 180 -
docs/src/ipykernel/ipykernel/inprocess/ipkernel.py | 180 -
docs/src/ipykernel/ipykernel/inprocess/manager.py | 75 -
docs/src/ipykernel/ipykernel/inprocess/socket.py | 59 -
.../ipykernel/inprocess/tests/__init__.py | 0
.../ipykernel/inprocess/tests/test_kernel.py | 68 -
.../inprocess/tests/test_kernelmanager.py | 108 -
docs/src/ipykernel/ipykernel/iostream.py | 347 -
docs/src/ipykernel/ipykernel/ipkernel.py | 360 -
docs/src/ipykernel/ipykernel/jsonutil.py | 173 -
docs/src/ipykernel/ipykernel/kernelapp.py | 454 -
docs/src/ipykernel/ipykernel/kernelbase.py | 728 --
docs/src/ipykernel/ipykernel/kernelspec.py | 172 -
docs/src/ipykernel/ipykernel/log.py | 20 -
docs/src/ipykernel/ipykernel/parentpoller.py | 114 -
docs/src/ipykernel/ipykernel/pickleutil.py | 448 -
docs/src/ipykernel/ipykernel/pylab/__init__.py | 0
.../ipykernel/ipykernel/pylab/backend_inline.py | 145 -
docs/src/ipykernel/ipykernel/pylab/config.py | 118 -
.../ipykernel/ipykernel/resources/logo-32x32.png | Bin 1084 -> 0 bytes
.../ipykernel/ipykernel/resources/logo-64x64.png | Bin 2180 -> 0 bytes
docs/src/ipykernel/ipykernel/serialize.py | 183 -
docs/src/ipykernel/ipykernel/tests/__init__.py | 44 -
docs/src/ipykernel/ipykernel/tests/test_connect.py | 63 -
.../ipykernel/ipykernel/tests/test_embed_kernel.py | 163 -
.../src/ipykernel/ipykernel/tests/test_jsonutil.py | 107 -
docs/src/ipykernel/ipykernel/tests/test_kernel.py | 244 -
.../ipykernel/ipykernel/tests/test_kernelspec.py | 109 -
.../ipykernel/ipykernel/tests/test_message_spec.py | 509 -
.../ipykernel/ipykernel/tests/test_pickleutil.py | 68 -
.../ipykernel/ipykernel/tests/test_serialize.py | 217 -
.../ipykernel/ipykernel/tests/test_start_kernel.py | 48 -
docs/src/ipykernel/ipykernel/tests/utils.py | 166 -
docs/src/ipykernel/ipykernel/zmqshell.py | 480 -
docs/src/ipykernel/setup.cfg | 2 -
docs/src/ipykernel/setup.py | 97 -
nbconvert/_version.py | 4 +-
nbconvert/exporters/__init__.py | 5 +-
nbconvert/exporters/asciidoc.py | 47 +
nbconvert/exporters/base.py | 119 +
nbconvert/exporters/export.py | 213 +-
nbconvert/exporters/exporter.py | 30 +-
nbconvert/exporters/exporter_locator.py | 87 +
nbconvert/exporters/html.py | 20 +-
nbconvert/exporters/latex.py | 34 +-
nbconvert/exporters/markdown.py | 39 +-
nbconvert/exporters/notebook.py | 13 +-
nbconvert/exporters/pdf.py | 44 +-
nbconvert/exporters/python.py | 16 +-
nbconvert/exporters/rst.py | 21 +-
nbconvert/exporters/script.py | 14 +-
nbconvert/exporters/slides.py | 15 +-
nbconvert/exporters/templateexporter.py | 148 +-
nbconvert/exporters/tests/files/notebook2.ipynb | 64 +-
nbconvert/exporters/tests/test_asciidoc.py | 41 +
nbconvert/exporters/tests/test_export.py | 6 +-
nbconvert/exporters/tests/test_latex.py | 16 +-
nbconvert/exporters/tests/test_pdf.py | 13 +-
nbconvert/exporters/tests/test_templateexporter.py | 79 +-
nbconvert/filters/__init__.py | 3 +-
nbconvert/filters/datatypefilter.py | 13 +-
nbconvert/filters/filter_links.py | 38 +
nbconvert/filters/highlight.py | 42 +-
nbconvert/filters/latex.py | 3 +-
nbconvert/filters/markdown.py | 48 +-
nbconvert/filters/pandoc.py | 26 +
nbconvert/filters/strings.py | 13 +-
nbconvert/filters/tests/test_datatypefilter.py | 10 +-
nbconvert/filters/tests/test_markdown.py | 28 +-
nbconvert/nbconvertapp.py | 74 +-
nbconvert/postprocessors/serve.py | 29 +-
nbconvert/preprocessors/base.py | 2 +-
nbconvert/preprocessors/convertfigures.py | 18 +-
nbconvert/preprocessors/csshtmlheader.py | 24 +-
nbconvert/preprocessors/execute.py | 130 +-
nbconvert/preprocessors/extractoutput.py | 18 +-
nbconvert/preprocessors/highlightmagics.py | 13 +-
nbconvert/preprocessors/sanitize.py | 138 +
nbconvert/preprocessors/svg2pdf.py | 23 +-
.../preprocessors/tests/fake_kernelmanager.py | 28 +
.../tests/files/Skip Exceptions.ipynb | 9 +-
nbconvert/preprocessors/tests/test_execute.py | 54 +-
nbconvert/preprocessors/tests/test_sanitize.py | 202 +
nbconvert/resources/style.min.css | 11573 -------------------
nbconvert/templates/asciidoc.tpl | 79 +
nbconvert/templates/html/basic.tpl | 76 +-
nbconvert/templates/html/full.tpl | 5 +
nbconvert/templates/html/mathjax.tpl | 6 +-
nbconvert/templates/latex/base.tplx | 78 +-
nbconvert/templates/latex/document_contents.tplx | 72 +
nbconvert/templates/latex/report.tplx | 2 +-
.../templates/latex/skeleton/display_priority.tplx | 6 +
nbconvert/templates/rst.tpl | 13 +-
nbconvert/templates/skeleton/Makefile | 24 +
nbconvert/templates/skeleton/display_priority.tpl | 6 +
nbconvert/tests/README.md | 1 +
nbconvert/tests/base.py | 4 +-
nbconvert/tests/fake_exporters.py | 9 +-
nbconvert/tests/files/Widget_List.ipynb | 4737 ++++++++
.../tests/files/markdown_display_priority.ipynb | 74 +
nbconvert/tests/test_nbconvertapp.py | 90 +-
nbconvert/utils/base.py | 20 +-
nbconvert/utils/lexers.py | 4 +-
nbconvert/writers/base.py | 21 +-
nbconvert/writers/files.py | 27 +-
nbconvert/writers/tests/test_files.py | 24 +-
readthedocs.yml | 5 +
setup.py | 47 +-
170 files changed, 7037 insertions(+), 21573 deletions(-)
diff --git a/docs/src/ipykernel/.gitignore b/.gitignore
similarity index 68%
rename from docs/src/ipykernel/.gitignore
rename to .gitignore
index 86345c8..5d9972f 100644
--- a/docs/src/ipykernel/.gitignore
+++ b/.gitignore
@@ -7,8 +7,7 @@ docs/source/api/generated
docs/source/config/options
docs/source/interactive/magics-generated.txt
docs/gh-pages
-IPython/html/notebook/static/mathjax
-IPython/html/static/style/*.map
+nbconvert/resources/style.min.css
*.py[co]
__pycache__
*.egg-info
@@ -19,4 +18,8 @@ __pycache__
.DS_Store
\#*#
.#*
-.coverage
+.coverage*
+htmlcov
+.cache
+docs/source/*.tpl
+docs/source/config_options.rst
diff --git a/docs/src/ipykernel/.mailmap b/.mailmap
similarity index 100%
rename from docs/src/ipykernel/.mailmap
rename to .mailmap
diff --git a/.travis.yml b/.travis.yml
new file mode 100644
index 0000000..6887316
--- /dev/null
+++ b/.travis.yml
@@ -0,0 +1,42 @@
+# Use a newer travis environment:
+# https://docs.travis-ci.com/user/trusty-ci-environment/
+# needs these two lines:
+sudo: required
+dist: trusty
+
+language: python
+python:
+ - "nightly"
+ - 3.5
+ - 3.4
+ - 3.3
+ - 2.7
+env:
+ global:
+ - PATH=$TRAVIS_BUILD_DIR/bin:$PATH
+addons:
+ apt:
+ packages:
+ - texlive-latex-extra # we need this for all the latex package we use, recommended is not enough
+ - texlive-generic-recommended # .. and more ...
+ - latex-xcolor # ... and more latex packages
+ - texlive-fonts-recommended # fonts...
+ - cm-super # more fonts
+ - texlive-xetex # latex to pdf converter
+ - inkscape # for svgs in pdf output
+before_install:
+ - git clone --quiet --depth 1 https://github.com/minrk/travis-wheels travis-wheels
+install:
+ - wget https://github.com/jgm/pandoc/releases/download/1.19.1/pandoc-1.19.1-1-amd64.deb && sudo dpkg -i pandoc-1.19.1-1-amd64.deb
+ - pip install -f travis-wheels/wheelhouse . codecov coverage
+ - pip install nbconvert[execute,serve,test]
+ - python -m ipykernel.kernelspec --user
+script:
+ # cd so we test the install, not the repo
+ - cd `mktemp -d`
+ - py.test --cov nbconvert -v --pyargs nbconvert
+after_success:
+ - codecov
+matrix:
+ allow_failures:
+ - python: "nightly"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b543329..d6aaa73 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,5 @@
# Contributing
We follow the
-[Jupyter Contribution Workflow](https://jupyter.readthedocs.org/en/latest/contrib_guide_code.html#contribution-workflow)
+[Jupyter Contribution Workflow](https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html)
and the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
diff --git a/docs/src/ipykernel/MANIFEST.in b/MANIFEST.in
similarity index 100%
rename from docs/src/ipykernel/MANIFEST.in
rename to MANIFEST.in
diff --git a/PKG-INFO b/PKG-INFO
deleted file mode 100644
index c6e55b4..0000000
--- a/PKG-INFO
+++ /dev/null
@@ -1,21 +0,0 @@
-Metadata-Version: 1.1
-Name: nbconvert
-Version: 4.2.0
-Summary: Converting Jupyter Notebooks
-Home-page: http://jupyter.org
-Author: Jupyter Development Team
-Author-email: jupyter at googlegroups.com
-License: BSD
-Description: UNKNOWN
-Keywords: Interactive,Interpreter,Shell,Web
-Platform: Linux
-Platform: Mac OS X
-Platform: Windows
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: System Administrators
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: BSD License
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 2.7
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.3
diff --git a/README.md b/README.md
index 8382433..218f2a6 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,8 @@
[](https://groups.google.com/forum/#!forum/jupyter)
[](https://travis-ci.org/jupyter/nbconvert)
-[](http://nbconvert.readthedocs.org/en/latest/?badge=latest)
+[](https://nbconvert.readthedocs.io/en/latest/?badge=latest)
+[](http://nbconvert.readthedocs.io/en/stable/?badge=stable)
[](https://codecov.io/github/jupyter/nbconvert?branch=master)
@@ -59,16 +60,23 @@ cd nbconvert
pip install -e .
```
+Running the tests after a dev install above:
+
+```
+pip install nbconvert[test]
+py.test --pyargs nbconvert
+```
+
## Resources
-- [Documentation for Jupyter nbconvert](https://nbconvert.readthedocs.org/en/latest/)
+- [Documentation for Jupyter nbconvert](https://nbconvert.readthedocs.io/en/latest/)
[[PDF](https://media.readthedocs.org/pdf/nbconvert/latest/nbconvert.pdf)]
- [nbconvert examples on GitHub](https://github.com/jupyter/nbconvert-examples)
- [Issues](https://github.com/jupyter/nbconvert/issues)
- [Technical support - Jupyter Google Group](https://groups.google.com/forum/#!forum/jupyter)
- [Project Jupyter website](https://jupyter.org)
-- [Documentation for Project Jupyter](https://jupyter.readthedocs.org/en/latest/index.html)
+- [Documentation for Project Jupyter](https://jupyter.readthedocs.io/en/latest/index.html)
[[PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)]
diff --git a/codecov.yml b/codecov.yml
new file mode 100644
index 0000000..2962fbc
--- /dev/null
+++ b/codecov.yml
@@ -0,0 +1,10 @@
+coverage:
+ status:
+ project:
+ default:
+ target: auto
+ threshold: 10
+ patch:
+ default:
+ target: 0%
+comments: off
diff --git a/docs/README.md b/docs/README.md
index 7039282..1205fd6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,33 +1,44 @@
# Documenting nbconvert
-[Documentation for `nbconvert`](https://nbconvert.readthedocs.org/en/latest/)
+[Documentation for `nbconvert`](https://nbconvert.readthedocs.io/en/latest/)
is hosted on ReadTheDocs.
## Build Documentation locally
1. Change directory to documentation root:
- $ cd docs
+ $ cd docs
-2. Install requirements:
+2. Create conda env (and install relevant dependencies):
- $ pip install -r requirements.txt
+ $ conda env create -f environment.yml
-3. Build documentation using Makefile for Linux and OS X:
+3. Activate the newly built conda environment `nbconvert_docs`
- $ make html
+ $ source activate nbconvert_docs
- or on Windows:
+4. Create an editable install for nbconvert using
- $ make.bat html
+ $ pip install -e ../.
-4. Display the documentation locally by navigating to
+ or if you want, `cd ..` and `pip install . -e`. But then you will need to `cd docs` before
+ continuing to the next step.
+
+5. Build documentation using Makefile for Linux and OS X:
+
+ $ make html
+
+ or on Windows:
+
+ $ make.bat html
+
+6. Display the documentation locally by navigating to
``build/html/index.html`` in your browser:
Or alternatively you may run a local server to display
the docs. In Python 3:
- $ python -m http.server 8000
+ $ python -m http.server 8000
In your browser, go to `http://localhost:8000`.
diff --git a/docs/autogen_config.py b/docs/autogen_config.py
index 9c9d01e..4507ade 100644
--- a/docs/autogen_config.py
+++ b/docs/autogen_config.py
@@ -19,7 +19,7 @@ Configuration options
=====================
Configuration options may be set in a file, ``~/.jupyter/jupyter_nbconvert_config.py``,
-or at the command line when starting nbconvert, i.e. ``jupyter nbconvert --config Application.log_level=10``.
+or at the command line when starting nbconvert, i.e. ``jupyter nbconvert --Application.log_level=10``.
"""
try:
diff --git a/docs/environment.yml b/docs/environment.yml
index 5d4462a..7992e3d 100644
--- a/docs/environment.yml
+++ b/docs/environment.yml
@@ -1,12 +1,15 @@
name: nbconvert_docs
channels:
-- willingcn
+ - conda-forge
dependencies:
-- python=3.5
+- python==3.5
- pandoc
- nbformat
- jupyter_client
+- ipython
+- sphinx>=1.5.1
+- sphinx_rtd_theme
+- tornado
+- entrypoints
- pip:
- - sphinx==1.3.6
- - nbsphinx
- - entrypoints
+ - nbsphinx>=0.2.12
diff --git a/docs/source/api/exporters.rst b/docs/source/api/exporters.rst
index 96066a1..50e0846 100644
--- a/docs/source/api/exporters.rst
+++ b/docs/source/api/exporters.rst
@@ -8,6 +8,15 @@ Exporters
:doc:`/config_options`
Configurable options for the nbconvert application
+.. autofunction:: export
+
+.. autofunction:: get_exporter
+
+.. autofunction:: get_export_names
+
+Exporter base classes
+---------------------
+
.. autoclass:: Exporter
.. automethod:: __init__
@@ -57,30 +66,3 @@ inherit either directly or indirectly from
.. autoclass:: PythonExporter
.. autoclass:: RSTExporter
-
-Specialized exporter functions
-------------------------------
-
-These functions are essentially convenience functions that
-wrap the functionality of the classes documented in the previous
-section.
-
-.. autofunction:: export_custom
-
-.. autofunction:: export_html
-
-.. autofunction:: export_slides
-
-.. autofunction:: export_latex
-
-.. autofunction:: export_pdf
-
-.. autofunction:: export_markdown
-
-.. autofunction:: export_python
-
-.. autofunction:: export_rst
-
-.. autofunction:: export_script
-
-.. autofunction:: export_by_name
\ No newline at end of file
diff --git a/docs/source/api/filters.rst b/docs/source/api/filters.rst
index 5ad5c9e..02f36e3 100644
--- a/docs/source/api/filters.rst
+++ b/docs/source/api/filters.rst
@@ -34,6 +34,8 @@ e.g. a terminal traceback) to HTML colors.
.. autofunction:: get_lines
+.. autofunction:: convert_pandoc
+
.. autoclass:: Highlight2HTML
.. autoclass:: Highlight2Latex
@@ -62,4 +64,4 @@ e.g. a terminal traceback) to HTML colors.
.. autofunction:: strip_files_prefix
-.. autofunction:: wrap_text
\ No newline at end of file
+.. autofunction:: wrap_text
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 1bc06f0..209b143 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -4,14 +4,62 @@
Architecture of nbconvert
=========================
-This is a high-level outline of the structure and objects in nbconvert,
-and how they are used in the pipeline of converting a notebook to any given format.
-
+This is a high-level outline of the basic workflow, structures and objects in nbconvert.
+Specifically, this exposition has a two-fold goal:
+
+ #. to alert you to the affordances available for customisation or direct contributions
+ #. to provide a map of where and when different events occur, which should aid in tracking down bugs.
+
+
+A detailed pipeline exploration
+===============================
+
+Nbconvert takes in a notebook, which is a JSON object, and operates on that object.
+
+This can include operations that take a notebook and return a notebook.
+For example, that operation could be to execute the notebook as though it were a continuous script; if it were executed ``--in-place`` then it would overwite the current notebook.
+Or it could be that we wish to systematically alter the notebook, for example by clearing all output cells.
+Format agnostic operations on cell content that do not violate the nbformat spec can be interpreted as a notebook to notebook conversion step; such operations can be performed as part of the preprocessing step.
+
+But often we want to have the notebook's structured content in a different format.
+Importantly, in many cases the structure of the notebook should be reflected in the structure of the output, adapted to the output's format.
+For that purpose, the original JSON structure of the document is crucial scaffolding needed to support this kind of structured output.
+In order to maintain structured, it can be useful to apply our conversion programmatically on the structure itself.
+To do so, when converting to formats other than the notebook, we use the `jinja`_ templating engine.
+
+The basic unit of structure in a notebook is the cell.
+Accordingly, since our templating engine is capable of expressing structure, the basic unit in our templates will often be specified at the cell level.
+Each cell has a certain type; the three most important cell types for our purposes are code, markdown, and raw NbConvert.
+Code cells can be split further into their input and their output.
+Operations can also occur separately on input and output and their respective subcomponents.
+Markdown cells and raw NbConvert cells do not have analogous substructure.
+
+The template's structure then can be seen as a mechanism for selecting content on which to operate.
+Because the template operates on individual cells, this has some upsides and drawbacks.
+One upside is that this allows the template to have access to the individual cell's metadata, which enables intelligently transforming the appropriate content.
+The transformations occur as a series of replacement rules and filters.
+For many purposes these filters take the form of external calls to `pandoc`_, which is a utility for converting between many different document formats.
+One downside is that this makes operations that require global coördination (e.g., cross referencing across cells) somewhat challenging to implement as filters inside templates.
+
+Note that all that we've described is happening in memory.
+This is crucial in order to ensure that this functionality is available when writing files is more challenging.
+Nonetheless, the reason for using nbconvert almost always involves producing some kind of output file.
+We take the in-memory object and write a file appropriate for the output type.
+
+The entirety of heretofore described process can be described as part of an ``Exporter``.
+``Exporter``\s often involves ``Preprocessor``\s, ``filters``, ``templates`` and ``Writer``\s.
+These classes and functions are described in greater detail below.
+
+Finally, one can apply a ``Postprocessor`` after the writing has occurred.
+For example, it is common when converting to slides to start a webserver and open a browser window with the newly created document (``--to slides --post serve``).
+
+Classes
+=======
.. _exporters:
Exporters
-=========
+---------
The primary class in nbconvert is the :class:`.Exporter`.
Exporters encapsulate the operation of turning a notebook into another format.
@@ -30,7 +78,7 @@ Once the notebook is loaded, it is preprocessed...
.. _preprocessors:
Preprocessors
-=============
+-------------
A :class:`.Preprocessor` is an object that transforms the content of the notebook to be exported.
The result of a preprocessor being applied to a notebook is always a notebook.
@@ -49,7 +97,7 @@ Once a notebook is preprocessed, it's time to convert the notebook into the dest
.. _templates_and_filters:
Templates and Filters
-=====================
+---------------------
Most Exporters in nbconvert are a subclass of :class:`.TemplateExporter`,
which means they use a `jinja`_ template to render a notebook into the destination format.
@@ -95,7 +143,7 @@ this is typically where you would stop, take your exported data, and go on your
.. _writers:
Writers
-=======
+-------
A :class:`.Writer` takes care of writing the resulting file(s) where they should end up.
There are two basic Writers in nbconvert:
@@ -108,7 +156,7 @@ Once the output is written, nbconvert has done its job.
.. _postprocessors:
Postprocessors
-==============
+--------------
A :class:`.Postprocessor` is something that runs after everything is exported and written to the filesystem.
The only postprocessor in nbconvert at this point is the :class:`.ServePostProcessor`,
@@ -120,3 +168,4 @@ which is used for serving `reveal.js`_ HTML slideshows.
.. _jinja: http://jinja.pocoo.org/
.. _filter: http://jinja.pocoo.org/docs/dev/templates/#filters
.. _reveal.js: http://lab.hakim.se/reveal-js
+.. _pandoc: http://pandoc.org/
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
index 26a6760..f7f4109 100644
--- a/docs/source/changelog.rst
+++ b/docs/source/changelog.rst
@@ -1,6 +1,54 @@
Changes in nbconvert
====================
+5.1.1
+-----
+
+`5.1.1 on GitHub <https://github.com/jupyter/nbconvert/milestones/5.1.1>`__
+
+- fix version numbering because of incomplete previous version number
+
+5.1
+---
+
+`5.1 on GitHub <https://github.com/jupyter/nbconvert/milestones/5.1>`__
+
+- improved CSS (specifically tables, in line with notebook) #498
+- improve in-memory templates handling #491
+- test improvements #516 #509 #505
+- new configuration option: IOPub timeout #513
+- doc improvements #489 #500 #493 #506
+- newly customizable: output prompt #500
+- more python2/3 compatibile unicode handling #502
+
+5.0
+---
+
+`5.0 on GitHub <https://github.com/jupyter/nbconvert/milestones/5.0>`__
+
+- Use :command:`xelatex` by default for latex export, improving unicode and font support.
+- Use entrypoints internally to access Exporters, allowing for packages to declare custom exporters more easily.
+- New ASCIIDoc Exporter.
+- New preprocessor for sanitised html output.
+- New general ``convert_pandoc`` filter to reduce the need to hard-code lists of filters in templates.
+- Use pytest, nose dependency to be removed.
+- Refactored Exporter code to avoid ambiguity and cyclic dependencies.
+- Update to traitlets 4.2 API.
+- Fixes for Unicode errors when showing execution errors on Python 2.
+- Default math font matches default Palatino body text font.
+- General documentation improvements. For example, testing, installation, custom exporters.
+- Improved link handling for LaTeX output
+- Refactored the automatic id generation.
+- New kernel_manager_class configuration option for allowing systems to be set up to resolve kernels in different ways.
+- Kernel errors now will be logged for debugging purposes when executing notebooks.
+
+4.3
+---
+
+`4.3 on GitHub <https://github.com/jupyter/nbconvert/milestones/4.3>`_
+
+- added live widget rendering for html output, nbviewer by extension
+
4.2
---
diff --git a/docs/source/conf.py b/docs/source/conf.py
index be5d053..7c1cb86 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -24,7 +24,10 @@ if os.environ.get('READTHEDOCS', ''):
# RTD doesn't use the repo's Makefile to build docs. We run
# autogen_config.py to create the config docs (i.e. Configuration Options
# page).
-
+ import sys, subprocess
+
+ # subprocess.run([sys.executable,'-m','pip','install','-e','../../.'])
+
with open('../autogen_config.py') as f:
exec(compile(f.read(), 'autogen_config.py', 'exec'), {})
@@ -41,6 +44,7 @@ extensions = [
'sphinx.ext.intersphinx',
'sphinx.ext.napoleon',
'nbsphinx',
+ 'IPython.sphinxext.ipython_console_highlighting',
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/customizing.ipynb b/docs/source/customizing.ipynb
index 412860e..576fb4f 100644
--- a/docs/source/customizing.ipynb
+++ b/docs/source/customizing.ipynb
@@ -11,7 +11,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "Under the hood, nbconvert uses [Jinja templates](http://jinja2.readthedocs.org/en/latest/intro.html) to specify how the notebooks should be formatted. These templates can be fully customized, allowing you to use nbconvert to create notebooks in different formats with different styles as well.\n",
+ "Under the hood, nbconvert uses [Jinja templates](https://jinja2.readthedocs.io/en/latest/intro.html) to specify how the notebooks should be formatted. These templates can be fully customized, allowing you to use nbconvert to create notebooks in different formats with different styles as well.\n",
"\n",
"Out of the box, nbconvert can be used to convert notebooks to plain Python files. For example, the following command converts the `example.ipynb` notebook to Python and prints out the result:"
]
@@ -280,12 +280,18 @@
" <div class=\"big_vertical_ellipsis\">⋮</div>\n",
"</div>\n",
"\n",
- "<h3>Extra HTML blocks (full.tpl)</h3>\n",
- "<div class=\"template_block\">header\n",
- " <pre><head></pre>\n",
- " <div class=\"template_block\">html_head</div>\n",
- " <pre></head></pre>\n",
- "</div>\n",
+ "<h3>Extra HTML blocks</h3>\n",
+ " <h4><pre>basic.tpl</pre></h4>\n",
+ " <div class=\"template_block\">output\n",
+ " <div class=\"template_block\">output_area_prompt</div>\n",
+ " <div class=\"template_block\">output (as above)</div>\n",
+ " </div>\n",
+ " <h4><pre>full.tpl</pre></h4>\n",
+ " <div class=\"template_block\">header\n",
+ " <pre><head></pre>\n",
+ " <div class=\"template_block\">html_head</div>\n",
+ " <pre></head></pre>\n",
+ " </div>\n",
"\n",
"<h3>Extra Latex blocks</h3>\n",
"<div class=\"template_block\">header\n",
diff --git a/docs/source/execute_api.rst b/docs/source/execute_api.rst
index 6b13918..d588007 100644
--- a/docs/source/execute_api.rst
+++ b/docs/source/execute_api.rst
@@ -79,7 +79,7 @@ Execution arguments (traitlets)
-------------------------------
The arguments passed to :class:`ExecutePreprocessor` are configuration options
-called `traitlets <http://traitlets.readthedocs.org/en/stable>`_.
+called `traitlets <https://traitlets.readthedocs.io/en/stable>`_.
There are many cool things about traitlets. For example,
they enforce the input type, and they can be accessed/modified as
class attributes. Moreover, each traitlet is automatically exposed
@@ -156,4 +156,4 @@ stopping the execution on the first error, we can keep executing the notebook
using the traitlet ``allow_errors`` (default is False). With
``allow_errors=True``, the notebook is executed until the end, regardless of
any error encountered during the execution. The output notebook, will contain
-the stack-traces and error messages for **all** the cells raising exceptions.
\ No newline at end of file
+the stack-traces and error messages for **all** the cells raising exceptions.
diff --git a/docs/source/external_exporters.rst b/docs/source/external_exporters.rst
index 2fb87c0..9dfe918 100644
--- a/docs/source/external_exporters.rst
+++ b/docs/source/external_exporters.rst
@@ -19,12 +19,12 @@ format designated by the ``FORMAT`` string as explained below.
Extending the built-in format exporters
---------------------------------------
A few built-in formats are available by default: `html`, `pdf`,
-`script`, `latex`. Each of these has its own _exporter_ with many
+`script`, `latex`. Each of these has its own *exporter* with many
configuration options that can be extended. Having the option to point to a
-different _exporter_ allows authors to create their own fully customized
+different *exporter* allows authors to create their own fully customized
templates or export formats.
-A custom _exporter_ must be an importable Python object. We recommend that
+A custom *exporter* must be an importable Python object. We recommend that
these be distributed as Python libraries.
.. _entrypoints:
@@ -126,6 +126,27 @@ We will use the following layout for our package to expose a custom exporter::
└── templates
└── test_template.tpl
+If you wished to create this same directory structure you could use the following commands
+when you are at the directory under which you wish to build your ``mypackage`` package:
+
+.. code-block:: bash
+
+ mkdir -p mypackage/mypackage/templates
+ touch mypackage/LICENSE.md
+ touch mypackage/setup.py
+ touch mypackage/mypackage/__init__.py
+ touch mypackage/mypackage/templates/test_template.tpl
+
+.. important::
+ You should not publish this package without adding content to your ``LICENSE.md`` file.
+ For example, ``nbconvert`` follows the Jupyter Project convention of using a Modified BSD
+ License (also known as New or Revised or 3-Clause BSD).
+ For a guide on picking the right license for your use case,
+ please see `choose a license <choosealicense.com>`_.
+ If you do not specify the license, your code may be `unusable by many open source projects`_.
+
+.. _`unusable by many open source projects`: http://choosealicense.com/no-license/
+
As you can see the layout is relatively simple, in the case where a template is not
needed we would actually have only one file with an Exporter implementation. Of course
you can change the layout of your package to have a more fine-grained structure of the
diff --git a/docs/source/install.rst b/docs/source/install.rst
index bbcac00..1bd6feb 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -3,7 +3,7 @@ Installation
.. seealso::
- `Installing Jupyter <https://jupyter.readthedocs.org/en/latest/install.html>`__
+ `Installing Jupyter <https://jupyter.readthedocs.io/en/latest/install.html>`__
Nbconvert is part of the Jupyter ecosystem.
Installing nbconvert
@@ -18,6 +18,11 @@ Nbconvert is packaged for both pip and conda, so you can install it with::
If you're new to Python, we recommend installing `Anaconda <https://www.continuum.io/downloads>`_,
a Python distribution which includes nbconvert and the other Jupyter components.
+.. important::
+
+ To unlock nbconvert's full capabilities requires Pandoc and TeX
+ (specifically, XeLaTeX). These must be installed separately.
+
Installing Pandoc
-----------------
@@ -30,3 +35,45 @@ To install pandoc on Linux, you can generally use your package manager::
On other platforms, you can get pandoc from
`their website <http://pandoc.org/installing.html>`_.
+
+Installing TeX
+--------------
+
+For converting to PDF, nbconvert uses the TeX document preparation
+ecosystem. It produces an intermediate ``.tex`` file which is
+compiled by the XeTeX engine with the LaTeX2e format (via the
+``xelatex`` command) to produce PDF output.
+
+.. versionadded:: 5.0
+
+ We use XeTeX as the rendering engine rather than pdfTeX (as
+ in earlier versions). XeTeX can access fonts through native
+ operating system libraries, it has better support for OpenType
+ formatted fonts and Unicode characters.
+
+To install a complete TeX environment (including XeLaTeX and
+the necessary supporting packages) by hand can be tricky.
+Fortunately, there are packages that make this much easier. These
+packages are specific to different operating systems:
+
+* Linux: `TeX Live <http://tug.org/texlive/>`_
+* macOS (OS X): `MacTeX <http://tug.org/mactex/>`_.
+* Windows: `MikTex <http://www.miktex.org/>`_
+
+Because nbconvert depends on packages and fonts included in standard
+TeX distributions, if you do not have a complete installation, you
+may not be able to use nbconvert's standard tooling to convert
+notebooks to PDF.
+
+PDF conversion on a limited TeX environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are only able to install a limited TeX environment, there are two main routes you could take to convert to PDF:
+
+1. Using TeX by hand
+ a. You could convert to ``.tex`` directly; this requires Pandoc.
+ b. edit the file to accord with your local environment
+ c. run ``xelatex`` directly.
+2. Custom exporter
+ a. You could write a :ref:`custom exporter <external_exporters>`
+ that takes your system's limitations into account.
diff --git a/docs/source/latex_citations.rst b/docs/source/latex_citations.rst
index 92fff47..b04f7c9 100644
--- a/docs/source/latex_citations.rst
+++ b/docs/source/latex_citations.rst
@@ -12,5 +12,5 @@ For an example of how this works, please see the `citations example`_ in
the nbconvert-examples_ repository.
.. _nbconvert-examples: https://github.com/jupyter/nbconvert-examples
-.. _citations example: https://nbviewer.jupyter.org/github/ipython/nbconvert-examples/blob/master/citations/Tutorial.ipynb
+.. _citations example: https://nbviewer.jupyter.org/github/jupyter/nbconvert-examples/blob/master/citations/Tutorial.ipynb
diff --git a/docs/source/nbconvert_library.ipynb b/docs/source/nbconvert_library.ipynb
index 6ee18fa..e1e56a7 100644
--- a/docs/source/nbconvert_library.ipynb
+++ b/docs/source/nbconvert_library.ipynb
@@ -8,7 +8,7 @@
"\n",
"In this notebook, you will be introduced to the programmatic API of nbconvert and how it can be used in various contexts. \n",
"\n",
- "A great [blog post](http://jakevdp.github.io/blog/2013/04/15/code-golf-in-python-sudoku/) by [@jakevdp](https://github.com/jakevdp) will be used to demonstrate. This notebook will not focus on using the command line tool. The attentive reader will point-out that no data is read from or written to disk during the conversion process. This is because nbconvert has been designed to work in memory so that it works well in a database or web-based environement too."
+ "A great [blog post](http://jakevdp.github.io/blog/2013/04/15/code-golf-in-python-sudoku/) by [@jakevdp](https://github.com/jakevdp) will be used to demonstrate. This notebook will not focus on using the command line tool. The attentive reader will point-out that no data is read from or written to disk during the conversion process. This is because nbconvert has been designed to work in memory so that it works well in a database or web-based environment too."
]
},
{
@@ -99,7 +99,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "The nbformat API returns a special type of dictionary. For this examle, you don't need to worry about the details of the structure (if you are interested, please see the [nbformat documentation](http://nbformat.readthedocs.org/en/latest/)).\n",
+ "The nbformat API returns a special type of dictionary. For this examle, you don't need to worry about the details of the structure (if you are interested, please see the [nbformat documentation](https://nbformat.readthedocs.io/en/latest/)).\n",
"\n",
"The nbconvert API exposes some basic exporters for common formats and defaults. You will start by using one of them. First, you will import one of these exporters (specifically, the HTML exporter), then instantiate it using most of the defaults, and then you will use it to process the notebook we downloaded earlier."
]
@@ -511,7 +511,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "The following demonstration, as requested in [a GitHub issue](https://github.com/ipython/nbconvert/pull/137#issuecomment-18658235), adds the ability to exclude a cell by index. \n",
+ "The following demonstration adds the ability to exclude a cell by index. \n",
"\n",
"Note: injecting cells is similar, and won't be covered here. If you want to inject static content at the beginning/end of a notebook, use a custom template."
]
@@ -522,16 +522,7 @@
"metadata": {
"collapsed": false
},
- "outputs": [
- {
- "name": "stderr",
- "output_type": "stream",
- "text": [
- "/Users/benjaminrk/conda/lib/python3.5/site-packages/ipykernel/__main__.py:9: DeprecationWarning: metadata {'config': True} was set from the constructor. Metadata should be set using the .tag() method, e.g., Int().tag(key1='value1', key2='value2')\n",
- "/Users/benjaminrk/conda/lib/python3.5/site-packages/ipykernel/__main__.py:10: DeprecationWarning: metadata {'config': True} was set from the constructor. Metadata should be set using the .tag() method, e.g., Int().tag(key1='value1', key2='value2')\n"
- ]
- }
- ],
+ "outputs": [],
"source": [
"from traitlets import Integer\n",
"from nbconvert.preprocessors import Preprocessor\n",
@@ -541,8 +532,10 @@
" \n",
" # I could also read the cells from nb.metadata.pelican if someone wrote a JS extension,\n",
" # but for now I'll stay with configurable value. \n",
- " start = Integer(0, config=True, help=\"first cell of notebook to be converted\")\n",
- " end = Integer(-1, config=True, help=\"last cell of notebook to be converted\")\n",
+ " start = Integer(0, help=\"first cell of notebook to be converted\")\n",
+ " end = Integer(-1, help=\"last cell of notebook to be converted\")\n",
+ " start.tag(config='True')\n",
+ " end.tag(config='True')\n",
" \n",
" def preprocess(self, nb, resources):\n",
" self.log.info(\"I'll keep only cells from %d to %d\", self.start, self.end)\n",
@@ -678,6 +671,7 @@
}
],
"metadata": {
+ "anaconda-cloud": {},
"kernelspec": {
"display_name": "Python 3",
"language": "python",
@@ -693,9 +687,9 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.5.1"
+ "version": "3.5.2"
}
},
"nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 1
}
diff --git a/docs/source/template_structure.html b/docs/source/template_structure.html
index 0c8b309..e4a82eb 100644
--- a/docs/source/template_structure.html
+++ b/docs/source/template_structure.html
@@ -88,12 +88,18 @@ This is an HTML fragment that gets included into a notebook & rst document
<div class="big_vertical_ellipsis">⋮</div>
</div>
-<h3>Extra HTML blocks (full.tpl)</h3>
-<div class="template_block">header
- <pre><head></pre>
... 30627 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/nbconvert.git
More information about the Python-modules-commits
mailing list