diff --git a/docs/source/exporting.md b/docs/source/exporting.md deleted file mode 100644 index 3e304bd..0000000 --- a/docs/source/exporting.md +++ /dev/null @@ -1,83 +0,0 @@ -.. module:: jupyter_contrib_nbextensions.nbconvert_support - - -Exporting -========= - -Some extensions add functionality you might want to keep when exporting a notebook -to another format using :mod:`nbconvert`. - -There are several parts to customize `nbconvert`output: - * *Preprocessors* to change content before conversion to another format - * *Postprocessors* to change content after conversion to another format - * *Exporters* to actually do the conversion to another format - * *Templates* provide customization using Jinja without writing an exporter - - -Preprocessors -------------- - - * CodeFoldingPreprocessor - preserve code folding at export:
- The preprocessor is installed by default. To enable codefolding with NbConvert, - you need to set the configuration parameter `NbConvertApp.codefolding=True`. - This can be done either in the `jupyter_nbconvert_config.py` file: - - c.NbConvertApp.codefolding=True - - or using a command line parameter when calling NbConvert: - - jupyter nbconvert --to html --NbConvertApp.codefolding=True mynotebook.ipynb - - * CollapsibleHeadingsPreprocessor - - * HighlighterPreprocessor - - * PyMarkdownPreprocessor - - * SVG2PDFPreprocessor
- Convert external `SVG` graphics to `PDF` using Inkscape. This is useful for LaTeX export. - This provides the functionality already provided by NbConvert for embedded images in cell output. - - -Postprocessors --------------- - - * HighlighterPostProcessor - - -Exporters ---------- - - * EmbedHTMLExporter
- Allows embedding images (pdf, svg and raster images) into a HTML file as base64 encoded binary, - instead of linking to them. - - jupyter nbconvert --to html_embed --NbConvertApp.codefolding=True mynotebook.ipynb - - * TocExporter - - * LenvsHTMLExporter - - * LenvsLatexExporter - - -Templates ---------- - -* highlighter - To be documented... - -* *nbextensions.tpl* and *nbextensions.tplx*
- Templates for notebook extensions that allow hiding code cells, output, or text cells. - Usage: - - jupyter nbconvert --template nbextensions mynotebook.ipynb - - The supported cell metadata tags are: - * `cell.metadata.hidden` - hide complete cell - * `cell.metadata.hide_input` - hide code cell input - * `cell.metadata.hide_output` - hide code cell output - - -* toc3 - To be done. diff --git a/docs/source/exporting.rst b/docs/source/exporting.rst new file mode 100644 index 0000000..5e26eb5 --- /dev/null +++ b/docs/source/exporting.rst @@ -0,0 +1,109 @@ +.. module:: jupyter_contrib_nbextensions.nbconvert_support + + +Exporting +========= + +Some extensions add functionality you might want to keep when exporting a notebook +to another format using :mod:`nbconvert`. + +There are several parts to customize :mod:`nbconvert` output: + * *Preprocessors* to change content before conversion to another format + * *Postprocessors* to change content after conversion to another format + * *Exporters* to actually do the conversion to another format + * *Templates* provide customization using Jinja without writing an exporter + + +Preprocessors +------------- + +Generic documentation for preprocessors can be found at +http://nbconvert.readthedocs.io/en/latest/api/preprocessors.html. + +Retaining Codefolding +^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: CodeFoldingPreprocessor + + +Coallapsible Headings +^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: CollapsibleHeadingsPreprocessor + +Retaining Highlighting +^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: HighlighterPreprocessor + + +Evaluating code in Markdown (PyMarkDown) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: PyMarkdownPreprocessor + +Converting linked SVG to PDF +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: SVG2PDFPreprocessor + + + +Postprocessors +-------------- + +Generic documentation for postprocessors can be found here +http://nbconvert.readthedocs.io/en/latest/api/postprocessors.html + +Retaining Highlighting +^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: HighlighterPostProcessor + + +Exporters +--------- + +Generic documentation for exporters can be found at +http://nbconvert.readthedocs.io/en/latest/api/exporters.html + +Embed images in HTML +^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: EmbedHTMLExporter + + Allows embedding images (pdf, svg and raster images) into a HTML file as base64 encoded binary, + instead of linking to them. + + jupyter nbconvert --to html_embed --NbConvertApp.codefolding=True mynotebook.ipynb + +Export Table of Contents +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: TocExporter + + +Templates +--------- + +Generic documentation on templates can be found at +http://nbconvert.readthedocs.io/en/latest/customizing.html + +To find the location of the custom templates you can use this function: +.. autofunction:: templates_directory + +Hiding cells +^^^^^^^^^^^^ + +*nbextensions.tpl* and *nbextensions.tplx*
+Templates for notebook extensions that allow hiding code cells, output, or text cells. +Usage: +:: + + jupyter nbconvert --template nbextensions mynotebook.ipynb + +The supported cell metadata tags are: + * `cell.metadata.hidden` - hide complete cell + * `cell.metadata.hide_input` - hide code cell input + * `cell.metadata.hide_output` - hide code cell output + diff --git a/docs/source/internals.rst b/docs/source/internals.rst index 74950a4..e6abd6e 100644 --- a/docs/source/internals.rst +++ b/docs/source/internals.rst @@ -109,60 +109,3 @@ This is a simple example for `readme.md`: --------- How this extension works. -NbConvert Support -================= - -Some extensions require additional effort when exporting them to other formats -using :mod:`nbconvert`. - - -Preprocessors -------------- - -Generic documentation for preprocessors can be found at -http://nbconvert.readthedocs.io/en/latest/api/preprocessors.html. - -.. autoclass:: CodeFoldingPreprocessor - -.. autoclass:: CollapsibleHeadingsPreprocessor - -.. autoclass:: HighlighterPreprocessor - -.. autoclass:: PyMarkdownPreprocessor - -.. autoclass:: SVG2PDFPreprocessor - - - -Postprocessors --------------- - -Generic documentation for postprocessors can be found here -http://nbconvert.readthedocs.io/en/latest/api/postprocessors.html - -.. autoclass:: HighlighterPostProcessor - - -Exporters ---------- - -Generic documentation for exporters can be found at -http://nbconvert.readthedocs.io/en/latest/api/exporters.html - -.. autoclass:: EmbedHTMLExporter - -.. autoclass:: TocExporter - -.. autoclass:: LenvsHTMLExporter - -.. autoclass:: LenvsLatexExporter - - -Templates ---------- - -Generic documentation on templates can be found at -http://nbconvert.readthedocs.io/en/latest/customizing.html - -.. autofunction:: templates_directory - diff --git a/src/jupyter_contrib_nbextensions/nbconvert_support/pre_codefolding.py b/src/jupyter_contrib_nbextensions/nbconvert_support/pre_codefolding.py index 93cbdb0..ce74dce 100644 --- a/src/jupyter_contrib_nbextensions/nbconvert_support/pre_codefolding.py +++ b/src/jupyter_contrib_nbextensions/nbconvert_support/pre_codefolding.py @@ -12,6 +12,19 @@ class CodeFoldingPreprocessor(Preprocessor): :mod:`nbconvert` Preprocessor for the code_folding nbextension. Folds codecells as displayed in the notebook. + + The preprocessor is installed by default. To enable codefolding with NbConvert, + you need to set the configuration parameter `NbConvertApp.codefolding=True`. + This can be done either in the `jupyter_nbconvert_config.py` file: + + :: + c.NbConvertApp.codefolding=True + + or using a command line parameter when calling NbConvert: + + :: + jupyter nbconvert --to html --NbConvertApp.codefolding=True mynotebook.ipynb + """ fold_mark = u'↔' diff --git a/src/jupyter_contrib_nbextensions/nbconvert_support/pre_svg2pdf.py b/src/jupyter_contrib_nbextensions/nbconvert_support/pre_svg2pdf.py index 5ec04ee..d353cff 100644 --- a/src/jupyter_contrib_nbextensions/nbconvert_support/pre_svg2pdf.py +++ b/src/jupyter_contrib_nbextensions/nbconvert_support/pre_svg2pdf.py @@ -1,10 +1,6 @@ # -*- coding: utf-8 -*- """ Preprocessor to convert svg graphics embedded in markdown to PDF. - -This preprocessor converts svg graphics embedded in markdown as -'![My graphic](graphics.svg)' -to PDF using Inkscape """ import errno @@ -62,11 +58,18 @@ def get_inkscape_executable_path(): class SVG2PDFPreprocessor(Preprocessor): """ Preprocessor to convert svg graphics embedded in notebook markdown to PDF. + Example for a markdown cell image: + + :: + ![My graphic](graphics.svg) Because LaTeX can't use SVG graphics, they are converted to PDF using inkscape_. This preprocessor is for SVG graphics in markdown only. For SVG - outputs from codecells, there is already the nbconvert preprocessor - :class:`nbconvert.preprocessors.SVG2PDFPreprocessor` + outputs from codecells, there is already the built-in nbconvert preprocessor + Configuration: + + :: + c.Exporter.preprocessors = [ "jupyter_contrib_nbextensions.nbconvert_support.SVG2PDFPreprocessor" ] .. _inkscape: https://inkscape.org/en """