Skip to content

Commit

Permalink
Use nbsphinx instead of converting .ipynb -> .rst
Browse files Browse the repository at this point in the history
  • Loading branch information
@mgeier
mgeier committed Jan 22, 2016
1 parent fe0a8a2 commit a32785f
Show file tree
Hide file tree
Showing 7 changed files with 12 additions and 761 deletions.
9 changes: 2 additions & 7 deletions docs/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext ipynb2rst
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext

help:
@echo "Please use \`make <target>' where <target> is one of"
Expand Down Expand Up @@ -51,7 +51,7 @@ help:
clean:
rm -rf $(BUILDDIR)/*

html: source/config_options.rst ipynb2rst
html: source/config_options.rst
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
Expand All @@ -60,11 +60,6 @@ source/config_options.rst:
python3 autogen_config.py
@echo "Created docs for config options"

ipynb2rst:
jupyter nbconvert --to rst source/customizing.ipynb --FilesWriter.build_directory=source
jupyter nbconvert --to rst source/nbconvert_library.ipynb --FilesWriter.build_directory=source
@echo "Converted notebooks to rst"

dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,6 @@ traitlets
jupyter_core
jupyter_client
nbformat
nbsphinx
sphinx_rtd_theme
-e git+https://github.com/ipython/ipykernel.git#egg=ipykernel
7 changes: 4 additions & 3 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.napoleon'
'sphinx.ext.napoleon',
'nbsphinx',
]

# Add any paths that contain templates here, relative to this directory.
Expand All @@ -48,7 +49,7 @@
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
source_suffix = ['.rst', '.ipynb']

# The encoding of source files.
#source_encoding = 'utf-8-sig'
Expand Down Expand Up @@ -91,7 +92,7 @@

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
exclude_patterns = ['.ipynb_checkpoints']

# The reST default role (used for this markup: `text`) to use for all
# documents.
Expand Down
142 changes: 2 additions & 140 deletions docs/source/customizing.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,149 +95,11 @@
},
{
"cell_type": "code",
"execution_count": 1,
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
"<!--\n",
"This is an HTML fragment that gets included into a notebook & rst document\n",
"-->\n",
"<style type=\"text/css\">\n",
"/* Overrides of notebook CSS for static HTML export */\n",
".jp-tpl-structure {\n",
" font-family: sans;\n",
"}\n",
"\n",
".template_block {\n",
" background-color: hsla(120, 60%, 70%, 0.2);\n",
" margin: 10px;\n",
" padding: 5px;\n",
" border: 1px solid hsla(120, 60%, 70%, 0.5);\n",
" border-left: 2px solid black;\n",
"}\n",
"\n",
".template_block:hover {\n",
" border-color: black;\n",
"}\n",
"\n",
".template_block pre {\n",
" background: transparent;\n",
" padding: 0;\n",
"}\n",
"\n",
".big_vertical_ellipsis {\n",
" font-size: 24pt;\n",
"}\n",
"\n",
"</style>\n",
"\n",
"<div class='jp-tpl-structure'>\n",
"<h3>Main page</h3>\n",
"<div class=\"template_block\">header</div>\n",
"\n",
"<div class=\"template_block\">body\n",
" <div class=\"template_block\">any_cell\n",
" <div class=\"template_block\">codecell\n",
" <div class=\"template_block\">input_group\n",
" <div class=\"template_block\">in_prompt</div>\n",
" <div class=\"template_block\">input</div>\n",
" </div>\n",
" <div class=\"template_block\">output_group\n",
" <div class=\"template_block\">output_prompt</div>\n",
" <div class=\"template_block\">outputs (see below)</div>\n",
" </div>\n",
" </div>\n",
" </div>\n",
" <div class=\"template_block\">any_cell\n",
" <div class=\"template_block\">markdowncell</div>\n",
" </div>\n",
" <div class=\"template_block\">any_cell\n",
" <div class=\"template_block\">rawcell</div>\n",
" </div>\n",
" <div class=\"template_block\">any_cell\n",
" <div class=\"template_block\">unknowncell</div>\n",
" </div>\n",
" <div class=\"big_vertical_ellipsis\">⋮</div>\n",
"</div>\n",
"\n",
"<div class=\"template_block\">footer</div>\n",
"\n",
"<h3>Outputs</h3>\n",
"\n",
"<div class=\"template_block\">outputs\n",
" <div class=\"template_block\">output\n",
" <div class=\"template_block\">execute_result</div>\n",
" </div>\n",
" <div class=\"template_block\">output\n",
" <div class=\"template_block\">stream_stdout</div>\n",
" </div>\n",
" <div class=\"template_block\">output\n",
" <div class=\"template_block\">stream_stderr</div>\n",
" </div>\n",
" <div class=\"template_block\">output\n",
" <div class=\"template_block\">display_data\n",
" <div class=\"template_block\">data_priority\n",
" <div class=\"template_block\">data_pdf / data_svg / data_png /\n",
" data_html / data_markdown / data_jpg / data_text /\n",
" data_latex / data_javascript / data_other\n",
" </div>\n",
" </div>\n",
" </div>\n",
" </div>\n",
" <div class=\"template_block\">output\n",
" <div class=\"template_block\">error\n",
" <div class=\"template_block\">traceback_line</div>\n",
" <div class=\"big_vertical_ellipsis\">⋮</div>\n",
" </div>\n",
" </div>\n",
" <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>&lt;head&gt;</pre>\n",
" <div class=\"template_block\">html_head</div>\n",
" <pre>&lt;/head&gt;</pre>\n",
"</div>\n",
"\n",
"<h3>Extra Latex blocks</h3>\n",
"<div class=\"template_block\">header\n",
" <div class=\"template_block\">docclass</div>\n",
" <div class=\"template_block\">packages</div>\n",
" <div class=\"template_block\">definitions\n",
" <div class=\"template_block\">title</div>\n",
" <div class=\"template_block\">date</div>\n",
" <div class=\"template_block\">author</div>\n",
" </div>\n",
" <div class=\"template_block\">commands\n",
" <div class=\"template_block\">margins</div>\n",
" </div>\n",
"</div>\n",
"<div class=\"template_block\">body\n",
" <div class=\"template_block\">predoc\n",
" <div class=\"template_block\">maketitle</div>\n",
" <div class=\"template_block\">abstract</div>\n",
" </div>\n",
" ... other fields as above ...\n",
" <div class=\"template_block\">postdoc\n",
" <div class=\"template_block\">bibliography</div>\n",
" </div>\n",
"</div>\n",
"</div>\n",
"\n"
],
"text/plain": [
"<IPython.core.display.HTML object>"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"outputs": [],
"source": [
"from IPython.display import HTML, display\n",
"with open('template_structure.html') as f:\n",
Expand Down
Loading

0 comments on commit a32785f

Please sign in to comment.