diff --git a/IPython/nbconvert/exporters/__init__.py b/IPython/nbconvert/exporters/__init__.py index 8383a2f..dca2a59 100755 --- a/IPython/nbconvert/exporters/__init__.py +++ b/IPython/nbconvert/exporters/__init__.py @@ -6,6 +6,6 @@ from .reveal import RevealExporter from .latex import LatexExporter from .markdown import MarkdownExporter from .python import PythonExporter -from .rst import RstExporter +from .rst import RSTExporter from .sphinx_howto import SphinxHowtoExporter from .sphinx_manual import SphinxManualExporter diff --git a/IPython/nbconvert/exporters/export.py b/IPython/nbconvert/exporters/export.py index f2d1766..83d3bcf 100755 --- a/IPython/nbconvert/exporters/export.py +++ b/IPython/nbconvert/exporters/export.py @@ -25,7 +25,7 @@ from .latex import LatexExporter from .markdown import MarkdownExporter from .python import PythonExporter from .reveal import RevealExporter -from .rst import RstExporter +from .rst import RSTExporter from .sphinx_howto import SphinxHowtoExporter from .sphinx_manual import SphinxManualExporter @@ -33,7 +33,7 @@ from .sphinx_manual import SphinxManualExporter # Classes #----------------------------------------------------------------------------- -def DocDecorator(f): +def DocDecorator(f): #Set docstring of function f.__doc__ = f.__doc__ + """ @@ -184,7 +184,7 @@ def export_python(nb, **kw): @DocDecorator def export_reveal(nb, **kw): """ - Export a notebook object to Reveal + Export a notebook object to a Reveal.js presentation """ return export(RevealExporter, nb, **kw) @@ -192,9 +192,9 @@ def export_reveal(nb, **kw): @DocDecorator def export_rst(nb, **kw): """ - Export a notebook object to RST + Export a notebook object to reStructuredText """ - return export(RstExporter, nb, **kw) + return export(RSTExporter, nb, **kw) @DocDecorator diff --git a/IPython/nbconvert/exporters/rst.py b/IPython/nbconvert/exporters/rst.py index e23e89a..7b84a76 100644 --- a/IPython/nbconvert/exporters/rst.py +++ b/IPython/nbconvert/exporters/rst.py @@ -22,7 +22,7 @@ from .exporter import Exporter # Classes #----------------------------------------------------------------------------- -class RstExporter(Exporter): +class RSTExporter(Exporter): """ Exports restructured text documents. """ @@ -38,5 +38,5 @@ class RstExporter(Exporter): @property def default_config(self): c = Config({'ExtractFigureTransformer':{'enabled':True}}) - c.merge(super(RstExporter,self).default_config) + c.merge(super(RSTExporter,self).default_config) return c diff --git a/IPython/nbconvert/nbconvertapp.py b/IPython/nbconvert/nbconvertapp.py index c6f1b66..652a1a4 100755 --- a/IPython/nbconvert/nbconvertapp.py +++ b/IPython/nbconvert/nbconvertapp.py @@ -1,8 +1,7 @@ #!/usr/bin/env python -"""NBConvert is a utility for conversion of IPYNB files. +"""NBConvert is a utility for conversion of .ipynb files. -Commandline interface for the NBConvert conversion utility. Read the -readme.rst for usage information +Command-line interface for the NbConvert conversion utility. """ #----------------------------------------------------------------------------- #Copyright (c) 2013, the IPython Development Team. @@ -23,42 +22,87 @@ import os import glob #From IPython -from IPython.core.application import BaseIPythonApplication -from IPython.config.application import catch_config_error -from IPython.utils.traitlets import Unicode, List, Instance, DottedObjectName, Type +from IPython.core.application import BaseIPythonApplication, base_aliases, base_flags +from IPython.config import catch_config_error, Configurable +from IPython.utils.traitlets import ( + Unicode, List, Instance, DottedObjectName, Type, CaselessStrEnum, +) from IPython.utils.importstring import import_item from .exporters.export import export_by_name, get_export_names, ExporterNameError -from .exporters.exporter import Exporter -from .writers.base import WriterBase +from IPython.nbconvert import exporters, transformers, writers from .utils.base import NbConvertBase #----------------------------------------------------------------------------- #Classes and functions #----------------------------------------------------------------------------- +nbconvert_aliases = {} +nbconvert_aliases.update(base_aliases) +nbconvert_aliases.update({ + 'format' : 'NbConvertApp.export_format', + 'notebooks' : 'NbConvertApp.notebooks', + 'writer' : 'NbConvertApp.writer_class', +}) + +nbconvert_flags = {} +nbconvert_flags.update(base_flags) +nbconvert_flags.update({ + 'stdout' : ( + {'NbConvertApp' : {'writer_class' : "StdoutWriter"}}, + "Write notebook output to stdout instead of files." + ) +}) + + class NbConvertApp(BaseIPythonApplication): """Application used to convert to and from notebook file type (*.ipynb)""" name = 'ipython-nbconvert' + aliases = nbconvert_aliases + flags = nbconvert_flags + + def _classes_default(self): + classes = [NbConvertBase] + for pkg in (exporters, transformers, writers): + for name in dir(pkg): + cls = getattr(pkg, name) + if isinstance(cls, type) and issubclass(cls, Configurable): + classes.append(cls) + return classes description = Unicode( - u"""This application is used to convert notebook files (*.ipynb). - An ipython config file can be used to batch convert notebooks in the - current directory.""") + u"""This application is used to convert notebook files (*.ipynb) + to various other formats.""") examples = Unicode(u""" - Running `ipython nbconvert` will read the directory config file and then - apply it to one or more notebooks. - + The simplest way to use nbconvert is + + > ipython nbconvert mynotebook.ipynb + + which will convert mynotebook.ipynb to the default format (probably HTML). + + You can specify the export format with `--format`. + Options include {0} + + > ipython nbconvert --format latex mynotebook.ipnynb + + You can also pipe the output to stdout, rather than a file + + > ipython nbconvert mynotebook.ipynb --stdout + Multiple notebooks can be given at the command line in a couple of different ways: > ipython nbconvert notebook*.ipynb > ipython nbconvert notebook1.ipynb notebook2.ipynb - > ipython nbconvert # this will use the config file to fill in the notebooks - """) - + + or you can specify the notebooks list in a config file, containing:: + + c.NbConvertApp.notebooks = ["my_notebook.ipynb"] + + > ipython nbconvert --config mycfg.py + """.format(get_export_names())) #Writer specific variables writer = Instance('IPython.nbconvert.writers.base.WriterBase', help="""Instance of the writer class used to write the @@ -78,55 +122,45 @@ class NbConvertApp(BaseIPythonApplication): #Other configurable variables - export_format = Unicode( - "", config=True, - help="""If specified, nbconvert will convert the document(s) specified - using this format.""") + export_format = CaselessStrEnum(get_export_names(), + default_value="full_html", + config=True, + help="""The export format to be used.""" + ) notebooks = List([], config=True, help="""List of notebooks to convert. - Search patterns are supported.""") - - nbconvert_aliases = {'format':'NbConvertApp.export_format', - 'notebooks':'NbConvertApp.notebooks', - 'writer':'NbConvertApp.writer_class'} - + Wildcards are supported. + Filenames passed positionally will be added to the list. + """) @catch_config_error def initialize(self, argv=None): - self.aliases.update(self.nbconvert_aliases) - super(NbConvertApp, self).initialize(argv) - - #Register class here to have help with help all - self.classes.insert(0, Exporter) - self.classes.insert(0, WriterBase) - self.classes.insert(0, NbConvertBase) - - #Init - self.init_config(self.extra_args) + self.init_notebooks() self.init_writer() - - def init_config(self, extra_args): - """ - Add notebooks to the config if needed. Glob each notebook to replace - notebook patterns with filenames. + def init_notebooks(self): + """Construct the list of notebooks. + If notebooks are passed on the command-line, + they override notebooks specified in config files. + Glob each notebook to replace notebook patterns with filenames. """ - #Get any additional notebook patterns from the commandline - if len(extra_args) > 0: - for pattern in extra_args: - self.notebooks.append(pattern) + # Specifying notebooks on the command-line overrides (rather than adds) + # the notebook list + if self.extra_args: + patterns = self.extra_args + else: + patterns = self.notebooks #Use glob to replace all the notebook patterns with filenames. filenames = [] - for pattern in self.notebooks: + for pattern in patterns: for filename in glob.glob(pattern): if not filename in filenames: filenames.append(filename) self.notebooks = filenames - def init_writer(self): """ Initialize the writer (which is stateless) @@ -134,15 +168,13 @@ class NbConvertApp(BaseIPythonApplication): self._writer_class_changed(None, self.writer_class, self.writer_class) self.writer = self.writer_factory(parent=self) - - def start(self, argv=None): + def start(self): """ - Ran after initiialization completed + Ran after initialization completed """ super(NbConvertApp, self).start() self.convert_notebooks() - def convert_notebooks(self): """ Convert the notebooks in the self.notebook traitlet diff --git a/IPython/nbconvert/transformers/__init__.py b/IPython/nbconvert/transformers/__init__.py index 2e5f782..e47b24c 100755 --- a/IPython/nbconvert/transformers/__init__.py +++ b/IPython/nbconvert/transformers/__init__.py @@ -1,5 +1,5 @@ # Class base Transformers -from .base import ConfigurableTransformer +from .base import Transformer from .convertfigures import ConvertFiguresTransformer from .svg2pdf import SVG2PDFTransformer from .extractfigure import ExtractFigureTransformer diff --git a/IPython/nbconvert/transformers/base.py b/IPython/nbconvert/transformers/base.py index 1fff970..825808e 100755 --- a/IPython/nbconvert/transformers/base.py +++ b/IPython/nbconvert/transformers/base.py @@ -23,7 +23,7 @@ from IPython.utils.traitlets import Bool # Classes and Functions #----------------------------------------------------------------------------- -class ConfigurableTransformer(NbConvertBase): +class Transformer(NbConvertBase): """ A configurable transformer Inherit from this class if you wish to have configurability for your @@ -53,7 +53,7 @@ class ConfigurableTransformer(NbConvertBase): Additional arguments """ - super(ConfigurableTransformer, self).__init__(**kw) + super(Transformer, self).__init__(**kw) def __call__(self, nb, resources): diff --git a/IPython/nbconvert/transformers/convertfigures.py b/IPython/nbconvert/transformers/convertfigures.py index 7587391..354f456 100644 --- a/IPython/nbconvert/transformers/convertfigures.py +++ b/IPython/nbconvert/transformers/convertfigures.py @@ -13,14 +13,14 @@ one format to another. # Imports #----------------------------------------------------------------------------- -from .base import ConfigurableTransformer +from .base import Transformer from IPython.utils.traitlets import Unicode #----------------------------------------------------------------------------- # Classes #----------------------------------------------------------------------------- -class ConvertFiguresTransformer(ConfigurableTransformer): +class ConvertFiguresTransformer(Transformer): """ Converts all of the outputs in a notebook from one format to another. """ diff --git a/IPython/nbconvert/transformers/csshtmlheader.py b/IPython/nbconvert/transformers/csshtmlheader.py index 5c65559..25dc511 100755 --- a/IPython/nbconvert/transformers/csshtmlheader.py +++ b/IPython/nbconvert/transformers/csshtmlheader.py @@ -19,7 +19,7 @@ from pygments.formatters import HtmlFormatter from IPython.utils import path -from .base import ConfigurableTransformer +from .base import Transformer from IPython.utils.traitlets import Unicode @@ -27,7 +27,7 @@ from IPython.utils.traitlets import Unicode # Classes and functions #----------------------------------------------------------------------------- -class CSSHTMLHeaderTransformer(ConfigurableTransformer): +class CSSHTMLHeaderTransformer(Transformer): """ Transformer used to pre-process notebook for HTML output. Adds IPython notebook front-end CSS and Pygments CSS to HTML output. diff --git a/IPython/nbconvert/transformers/extractfigure.py b/IPython/nbconvert/transformers/extractfigure.py index 4ff94b9..1c28104 100755 --- a/IPython/nbconvert/transformers/extractfigure.py +++ b/IPython/nbconvert/transformers/extractfigure.py @@ -15,13 +15,13 @@ notebook file. The extracted figures are returned in the 'resources' dictionary import sys from IPython.utils.traitlets import Unicode -from .base import ConfigurableTransformer +from .base import Transformer #----------------------------------------------------------------------------- # Classes #----------------------------------------------------------------------------- -class ExtractFigureTransformer(ConfigurableTransformer): +class ExtractFigureTransformer(Transformer): """ Extracts all of the figures from the notebook file. The extracted figures are returned in the 'resources' dictionary. diff --git a/IPython/nbconvert/transformers/latex.py b/IPython/nbconvert/transformers/latex.py index 22cc203..be1f5ac 100755 --- a/IPython/nbconvert/transformers/latex.py +++ b/IPython/nbconvert/transformers/latex.py @@ -17,14 +17,14 @@ from __future__ import print_function, absolute_import # Our own imports # Needed to override transformer -from .base import (ConfigurableTransformer) +from .base import (Transformer) from IPython.nbconvert import filters #----------------------------------------------------------------------------- # Classes #----------------------------------------------------------------------------- -class LatexTransformer(ConfigurableTransformer): +class LatexTransformer(Transformer): """ Converter for latex destined documents. """ diff --git a/IPython/nbconvert/transformers/revealhelp.py b/IPython/nbconvert/transformers/revealhelp.py index 8bdc65c..96d69f1 100755 --- a/IPython/nbconvert/transformers/revealhelp.py +++ b/IPython/nbconvert/transformers/revealhelp.py @@ -12,14 +12,14 @@ # Imports #----------------------------------------------------------------------------- -from .base import ConfigurableTransformer +from .base import Transformer from IPython.utils.traitlets import Unicode #----------------------------------------------------------------------------- # Classes and functions #----------------------------------------------------------------------------- -class RevealHelpTransformer(ConfigurableTransformer): +class RevealHelpTransformer(Transformer): url_prefix = Unicode('//cdn.jsdelivr.net/reveal.js/2.4.0', config=True, diff --git a/IPython/nbconvert/transformers/sphinx.py b/IPython/nbconvert/transformers/sphinx.py index 935ec12..8c4fa7c 100755 --- a/IPython/nbconvert/transformers/sphinx.py +++ b/IPython/nbconvert/transformers/sphinx.py @@ -33,7 +33,7 @@ from pygments.formatters import LatexFormatter from IPython.utils.traitlets import Unicode, Bool # Needed to override transformer -from .base import (ConfigurableTransformer) +from .base import (Transformer) from IPython.nbconvert.utils import console @@ -41,7 +41,7 @@ from IPython.nbconvert.utils import console # Classes and functions #----------------------------------------------------------------------------- -class SphinxTransformer(ConfigurableTransformer): +class SphinxTransformer(Transformer): """ Sphinx utility transformer.