spatialaudio / nbsphinx

:ledger: Sphinx source parser for Jupyter notebooks

Jupyter Notebook Tools for Sphinx

nbsphinx is a Sphinx extension that provides a source parser for *.ipynb files. Custom Sphinx directives are used to show Jupyter Notebook code cells (and of course their results) in both HTML and LaTeX output. Un-evaluated notebooks -- i.e. notebooks without stored output cells -- will be automatically executed during the Sphinx build process.

Quick Start:

1. Install nbsphinx
2. Edit your conf.py and add 'nbsphinx' to extensions.
3. Edit your index.rst and add the names of your *.ipynb files to the toctree.
4. Run Sphinx!

Online documentation (and example of use):

https://nbsphinx.readthedocs.io/

Source code repository (and issue tracker):

https://github.com/spatialaudio/nbsphinx/

License:

MIT -- see the file LICENSE for details.

nbsphinx's Issues

rst_prolog and rst_epilog break notebook loading

Any ideas. Here is the log:
sphinx-err-glebxw.txt

Docs: Clarification Raw Cell Options

I've used IPython for a couple years, but hadn't realized the raw cells had other formats. It took some time for me to find in it IPython 3. I suggest clarifying after selecting a cell:

1. First select Raw NBConvert
2. Then next to Cell Toolbar: select Raw Cell Format
3. Choose one of the format options
   ...

These options may differ for Jupyer (IPython 4+). BTW, this is a great extension. Finding it this week has been most fortunate.

mention pandoc dependency in the documentation

The README.rst nor the docs on ReadTheDocs mention pandoc as a dependency.

Make sure to handle image size metadata correctly

See ipython/ipython#4685 and it's solution ipython/ipython#5095.

Convert directly to docutils without intermediate RST

Currently there are some markdown formatting difficulties that can arise when converting to HTML. For example, a link like [nbsphinx](https://github.com/spatialaudio/nbsphinx) which should render as nbsphinx (cf. nbsphinx) won't be displayed properly because this text can't easily be represented in the intermediate RST.

Since sphinx can easily produce documents directly from markdown (e.g. using recommonmark), it would be nice if it were possible to skip the RST altogether as this would more reliably reproduce the desired formatting from the notebook. Currently I am using nbconvert to get markdown output and then producing HTML with Sphinx instead of using nbsphinx because of such formatting issues.

cc: @fperez @takluyver

HTML: Add download link for the current notebook

Ideally, this should already work with the "Source" link (but currently it doesn't).

We could also include an (optional) link above or below the first section title (like here) or at the bottom of the page (like here).

readthe docs github link is 404

For example, on the page http://nbsphinx.readthedocs.org/en/0.2.4/pre-executed.html

The "Edit on Github" link points to https://github.com/spatialaudio/nbsphinx/blob/0.2.4/doc/pre-executed.rst which gives a 404 (it should be linking to ipynb). I have no idea how to fix this, otherwise I would submit a PR.

Enable equation numbers

Ideally, with the possibility of links between notebooks.

http://nbviewer.jupyter.org/urls/gist.githubusercontent.com/ahmadia/4b615bdb6f6b8e49dbc8/raw/d846ec263ec604de8d2c2fc75bf97fa2cbd4a160/Manual%2520MathJax%2520Equation%2520Tags%2520in%2520the%2520Jupyter%2520Notebook.ipynb

ipython/ipython#4113

Notebook extension for enabling equation numbers:
https://github.com/ipython-contrib/IPython-notebook-extensions/tree/master/nbextensions/usability/equation-numbering (dead link)
https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/equation-numbering/readme.html

http://stackoverflow.com/questions/18823779/ipython-notebook-and-mathjax-labeled-equations

numbering SymPy output:
http://nbviewer.ipython.org/github/MalteJin/Manual-equation-numbering/blob/branch/Manual%20equation%20numbering.ipynb

https://docs.mathjax.org/en/latest/tex.html#automatic-equation-numbering

LaTeX: Images are too big

I already posted this on the Jupyter mailing list, I'm just repeating it here:

The images (which look fine in the HTML output) are hideously large in the LaTeX output, see e.g.
https://media.readthedocs.org/pdf/nbsphinx/0.2.2/nbsphinx.pdf

This also happens with the "normal" nbconvert.

How can I get a reasonable image size?
Ideally this should work out-of-the box ...

I don't know if that's addressed already somewhere, I only found some mentions of image size in jupyter/nbconvert#178 and https://gist.github.com/kroger/3856821.

Any further pointers would be very helpful!

Links to other notebooks in markdown cells

Is nbsphinx able to convert relative links to other notebooks in markdown cells to links to links html files?

It seems that the href is correct, but the ipynb extension needs to be converted to html.

cc @gnestor.

Undefined variable in _generate_output_format

I ran into an issue where latex_datatype wasn't defined in _generate_output_type when running a nbsphinx on a precomputed notebook.

This code appears to be untested; all code should be tested.

encapsulate markdown cells in sphinx directives

In #45 a special cell metadata switch to encapsulate the whole cell in a sphinx directive in the rendered doc is proposed.

In the rendered doc the cell content should be displayed as eg an admonition (warning, seealso, note,..). At the same time, the look and feel in the notebook should be almost similar.

nbsphinx gives WARNING: file not found: when valid path to a directory is provided in a link

In the jupyter notebook documentation a link to a directory is specified in the line (if you wish, you can see the link as part of our live documentation):

See [Extending the Notebook](../../extending) for more documentation about writing nbextensions, server extensions, and bundler extensions.

This directory successfully resolves on html export: http://jupyter-notebook.readthedocs.io/en/latest/extending/

However, when building the html, it raises an error:

> WARNING: file not found: 'extending'

I looked into fixing this with a quick fix to indicate that it wasn't supposed to be a file (e.g., [Extending the Notebook](../../extending/)) but it doesn't seem to recognise that you can also link to directories in this manner.

I think this arises because of the code at: https://github.com/spatialaudio/nbsphinx/blob/master/nbsphinx.py#L911

I'm not sure what your preferred solution to this would be. It could either look for a trailing / and then treat it as a directory call (meaning the current code can mostly be untouched) or it should fall back when a file is not found and test whether a directory with the same name is present in the same location.

Make pandoc spit out "code-block" instead of "code"

The code directive is not officially supported by Sphinx, therefore the highlight_language option I used in 77dc80e is not working.

Either this issue has to be fixed in Sphinx: sphinx-doc/sphinx#2155 (which, according to the comments, seems unlikely), or we have to make pandoc (which is used in markdown2rst) generate code-block instead of code directives.

All this only affects code within Markdown cells, the actual code cells are handled separately (not by pandoc).

For reference:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#code
http://www.sphinx-doc.org/en/stable/markup/code.html

Check if cell attachments work

... and include an example in the docs.

http://nbformat.readthedocs.org/en/latest/format_description.html#cell-attachments

conda-forge recipe breaks

Hi nbsphinx team! I'd like to submit an nbsphinx recipe to conda-forge, so that I can build another package (i.e. PyMC3) in its totality, but I noticed that the build keeps breaking because of an import error. [PR].

More specifically, conda-forge scripts require at least one test to be run, (please see here), but I wasn't sure what would be the appropriate test to run after building and running. Would you be kind enough to advise please?

toctree lists header level information lost/mixed up.

Hi all,

first, congrats to a great project! Very useful!

I've noticed that the header level information from the .ipynb files are not consistently transferred to .html.

E.g. this the result of running python3 setup.py build_sphinx locally on a clone of this library https://github.com/spatialaudio/nbsphinx:

And this is what it should like (please only look at the structure):

Do you see how the levels were changed? I noticed this bug for the first time on my own project, so it seems to be consistent on my system (Python 3.5.0):

docutils==0.12 ipdb==0.8.1 ipykernel==4.3.1 ipython==4.2.0 ipython-genutils==0.1.0 ipywidgets==5.1.5 jupyter==1.0.0 jupyter-client==4.3.0 jupyter-console==4.1.1 jupyter-core==4.1.0 nbconvert commit q64aeeefa872be8c8885437b20fa1f0f6c45b8d58 pypandoc==1.1.3 Sphinx==1.4.2 sphinx-bootstrap-theme==0.4.9 sphinx-rtd-theme==0.1.9

Thanks for any ideas!

ENC: Hide Jupyter cell; retain output

Is there a way to only output the result of a Jupyter cell, while hiding the code?

The context is, I have plots that I would like to display as a gallery in rtds, but the code cells are distracting. I'm not aware of this option to hide cells in Jupyter... In fact, it looks like hiding input cells is on their todo list for 4.2. In the meantime, in that same post, there is a hack for it.

Your thoughts on adding this feature either now or in the future to nbsphinx...?

UnboundLocalError: local variable 'latex_datatype' referenced before assignment

When using nbsphinx 0.2.8, I have an UnboundLocalError (see e.g. https://readthedocs.org/projects/spectrogrism/builds/4035544/):

Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/spectrogrism/envs/dev/local/lib/python2.7/site-packages/nbsphinx.py", line 804, in _get_output_type
    return html_datatype, latex_datatype
UnboundLocalError: local variable 'latex_datatype' referenced before assignment

I guess this relates to the fact that variable latex_datatype is not necessarily defined in nbsphinx._get_output_type() if none of the datatypes in DISPLAY_DATA_PRIORITY_LATEX is in output.data.

"[Errno 2] No such file or directory" when a subdirectory is added

Thanks for nbsphinx, this is going to be a really useful time-saving tool.

I am however running into an error that is causing me lots of confusion

C:\B\nbsphinx_mytest\docs>sphinx-build source build
Running Sphinx v1.3.4
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: 3 added, 0 changed, 0 removed
reading sources... [100%] notebooks/notebook2
Exception occurred:
  File "c:\users\jonathan\anaconda3\lib\site-packages\nbsphinx.py", line 366, in parse
    with open(dest, 'wb') as f:
FileNotFoundError: [Errno 2] No such file or directory: 'C:\\B\\nbsphinx_mytest\\docs\\build\\.doctrees\\nbsphinx\\notebooks\\notebook2_4_0.png'
The full traceback has been saved in C:\Users\Jonathan\AppData\Local\Temp\sphinx-err-28u403cp.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

The log file is here (had to change .log to .txt to attach):
sphinx-err-28u403cp.txt

You can see the simple folder structure I have on nbsphinx_mytest repo -- displaying (now incorrectly) at http://nbsphinx-mytest.readthedocs.org/) that my ```index.rst''' is basically just:

.. toctree::
    :maxdepth: 3
    :glob:

    notebook1
    notebooks/*

and I have a single notebook2.ipynb (with a plot) inside the notebooks folder inside the source folder.

The extra bizarre thing about this is that even after I strip my index.rst of the glob and any reference to the subdirectory, so it's now nothing more than:

.. toctree::
    :maxdepth: 3

    notebook1

and I then rebuild (even after deleting the earlier build directory) I the same error now persists on a new build. It is as if nbsphinx is searching subfolders whether instructed to the earlier error is not being cleared out.

It may be relevant that it now says running Sphinx v1.3.4. Could that be a problem (because I'm pretty sure I'd not encountered this problem before when I was running similar experiments with subdirectories on v1.3.3). Worth noting that I'm now getting a similar type error when I clone this nbsphinx repo and run your examples with sphinx-build . build (it wasn't clear from the instructions if that's the right way).

embed markdown tables automatically generated

I would like to embed tables and plots generated on the fly in markdown cells based on some (hidden) initialization cells.

This is possible in the jupyter notebook thanks to this extension python-markdown.

According to the extension documentation it is possible to have the same behavior exporting via nbconvert using a pre-processor (here the preprocessor source code) :

Exporting
In order to have nbconvert show the computed Python output when exporting to another format, use the pre_pymarkdown.py preprocessor. If you used the python setup.py install command to install the IPython-contrib extension package, this will already be installed.
For manual setup, you need to copy this file to a location within the Python path (or extend PYTHONPATH). Additionally, you need to add these two lines to your jupyter_nbconvert_config.py configuration file:
c = get_config()
c.Exporter.preprocessors = ['pre_pymarkdown.PyMarkdownPreprocessor']

This works when I manually convert a notebook to html using nbconvert, but not when I try to build the doc with sphinx.

Any suggestion? Is this the best approach? (related in end to issue #15)

Thanks ;-)

Move CSS string from <body> to <head>

There was a related question on the sphinx-users mailing list, but no solution:

https://groups.google.com/forum/?nomobile=true#!searchin/sphinx-users/css/sphinx-users/iG0fB9-JdNM/Le-rz_zbRHUJ

Also, the CSS string should only be included in the pages which actually need it.

embed bokeh plots

I am wondering if there is a way to embed bokeh plot (and probably other rich js display) in the resulting sphinx doc ?
The first attempt led to the bokeh javascript loading step being deleted, the result of output_notebook() is being suppressed by nbsphinx.
That step could be solved by embedding the bokeh.js link in the html template, but then the bokeh "frame" gets an absolute position in the page (top left of the web page).
Did you face that issue already ?

Spaces in notebook filename

Hi!

I have ipython notebook named "what is up.ipynb" containing one cell:

from IPython.display import Image
Image(filename='big.jpg')

The generated image will have name "what is up_0_0.jpeg", and sphinx will look for "whatisup_0_0.jpeg" which contains no spaces. So, the final document will have a broken image link. "WARNING: image file not readable: _build/doctrees/nbsphinx/whatisup_0_0.jpeg" will be generated. I'm on Windows with python 2.7.10, having latest stable versions of sphinx and nbspinx. Manually removing spaces in image filenames is a quick way of fixing it.

Try if citations work

See https://github.com/jupyter/nbconvert-examples/tree/master/citations

LaTeX: Download non-local images

... and take care of the warning message:

WARNING: nonlocal image URI found: http...

This should probably be part of a separate Sphinx extension, since it is not directly related to Jupyter notebooks.

HTML <audio> element in Markdown cells doesn't work on readthedocs.org

See for example http://nbsphinx.readthedocs.io/en/0.2.10/markdown-cells.html#HTML-Elements-(HTML-only).

Strangely, the <video> element that comes right after, works fine.

If the <audio> element appears in a normal reST file, it works fine.

LaTeX: SVG support

This will hopefully be fixed soon in Sphinx itself:
sphinx-doc/sphinx#1907
sphinx-doc/sphinx#2166

assertion error in `depart_code_latex`

The assertion assert lines[0] == '' fails for the ipywidgets documentation (and has been failing for some time).

Instrumenting the code locally shows that lines is equal to ['}', ''].

Exception occurred:
  File "/Users/scorlay/jupyter/spatialaudio/nbsphinx/nbsphinx.py", line 1156, in depart_code_latex
    assert lines[0] == ''

wrapping long output

How can long output be wrapped correctly?

In some notebooks I print long lines, which extend over the screen (see rendered html here: http://wradlib.org/wradlib-docs/latest/simple_plot.html). How can it be done, that the lines are wrapped at the "end" of the code-boxes?

JFTR, the notebook is rendered with runipy and then sphinxed nbsphinx. Great tool, btw.

notebook crossreferences that work in one output format(html) but break in another (LaTeX)

Cross references written in terms of html crossrefs are not always interpreted appropriately by nbsphinx in LaTeX export.

for example in https://github.com/jupyter/nbconvert/blob/master/docs/source/architecture.rst we have

see-also::

    `Custom Preprocessors <nbconvert_library.html#Custom-Preprocessors>`_

which is correctly handled for html export but in the LaTeX export this is converted to:

\sphinxstrong{See also:}
{\hyperref[external_exporters:external\string-exporters]{\sphinxcrossref{\DUrole{std,std-ref}{Writing a custom Exporter}}}}

When it should be

\sphinxstrong{See also:}
\hyperref[nbconvert_library:Custom-Preprocessors]{\sphinxcrossref{\DUrole{std,std-ref}{Custom-Preprocessors}}}

What's weird is the wrong one is taking content from two different places, one is a chapter heading that has the content "Customizing exporters" the other is a heading with the content "Writing a custom \texttt{Exporter}".

As a hint — the :doc: directive seems to be successfully linking inside .ipynb files (i.e., :doc:nbconvert_library seems to successfully convert to {\hyperref[nbconvert_library::doc]{\sphinxcrossref{\DUrole{doc}{Using nbconvert as a library}}}}).

WARNING: Pygments lexer name 'ipython3' is not known

I get thousands of warnings:

WARNING: Pygments lexer name 'ipython3' is not known

when I run make html after adding 'nbsphinx' to extensions.

This happens even with an empty index.rst file (it seems to find my .ipynb_checkpoints folder).

---

python 3.5.1
ipython 4.1.1
nbconvert 4.1.0
jupyter 1.0.0
pygments 2.1

Maplotlib figures do not render

After building, it seems my plots for matplotlib are not rendering. In place of the images are paths to files in the doctrees folder, e.g:

_build%5Cdoctrees%5Cnbsphinx%5Cshowcase_121_1.png

Those images do exist at these paths, but are not being rendered somehow make html. The errors says these files are not readable, which is odd since they are generated from the notebook. Any thoughts?

HTML: support for PDF images

The same way as SVG images should be converted to PDF for LaTeX output (see #3), PDF images should be converted to SVG for HTML output.

Hidden cells with hide_input argument

Hello,

Jupyter notebooks do have the ability to hide a cell with "hide_input": true metadata. I think, this should be handled by nbsphinx in the same way as "nbsphinx": "hidden".

My suggestion:

Extend

{%- if cell.metadata.nbsphinx != 'hidden' %}

with

{%- if cell.metadata.nbsphinx != 'hidden' or cell.metadata.hide_input is not True %}

Bye, Jonathan

Is there an in-place mechanism for converting a single notebook for nbsphinx dev purposes?

Hi, right now it seems like the only way to see the output of nbsphinx on a notebook is indirectly through sphinx. Is there an API or some straightforward workflow for use in the style of nbconvert on a single notebook to see what the comparable html/rst/LaTeX output would be?

One example of a case that seems like too much of a hassle to fight with indirectly is debugging #82. If there is a more iterative way of interacting with the nbsphinx codebase and to try out these things, then I think I'd be able to contribute here more easily.

If not, no worries, I just wanted to check.

How to include the JavaScript for widgets?

Is it really necessary to load jupyter_sphinx.embed_widgets?

Since #76, only adding the JS file is necessary, nothing else from jupyter_sphinx.embed_widgets is needed, right?

What about adding a config option like nbsphinx_widgets?
This could be False by default and True if widgets should be displayed.
It could even be set to an alternative path to the JS file (e.g. for offline use).

See also jupyter/jupyter-sphinx#3.

Using nbsphinx with autosummary

Hi,

I'm trying to run nbsphinx as per the docs. I am also using the autosummary extension. I get the following error:

[autosummary] generating autosummary for: api.rst, changelog.rst, examples.rst, examples/README.rst, examples/SMHM.ipynb.rst ...
...
IOError: [Errno 2] No such file or directory: u'/home/steven/Documents/Projects/MRP/mrpy/docs/examples/SMHM.ipynb.rst'

As you can see, it's trying to add the rst to the end of SMHM.ipynb and not finding it. Any idea what's going wrong?

Syntax highlighting of python 2 notebooks not working on readthedocs

I'm not sure if this is the appropriate place for this, so feel free to close if it's not.

On readthedocs, I don't get syntax highlighting (conf file): http://cobrapy-test.readthedocs.org/en/latest/getting_started.html#Reactions

However, I do get syntax highlighting when I make the docs locally

Syntax highlighting doesn't work for Python cells with magic

If I have a cell in a Python 3 notebook that says e.g.

%%time
# some python code

then when rendered with nbsphinx, the # some python code looses its syntax highlighting. Could it be made so that the syntax highlighting is kept, the same way it does in Jupyter notebook itself?

Some info about my setup incase its just a bug:

nbsphinx==0.2.9
Sphinx==1.4.6
ipython==5.1.0
jupyter-client==4.3.0
jupyter-core==4.1.1

NoSuchKernel error

After running smoothly for many builds, my readthedocs build is failing with this error. All I did was add a few more notebooks (which I later removed). Could it be that nbphinx is no longer able to find and run a kernel it needs?

Here is more detail on the failing build
http://readthedocs.org/projects/dev-ii-seminar/builds/3700606/

and the exception listed there:

Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/dev-ii-seminar/envs/latest/local/lib/python2.7/site-packages/jupyter_client/kernelspec.py", line 143, in get_kernel_spec
    raise NoSuchKernel(kernel_name)
NoSuchKernel
The full traceback has been saved in /tmp/sphinx-err-fz0JLj.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

Impossible to build notebooks with Scipy requirements on readthedocs.io

Hi there,

I've been trying to use nbsphinx to build some code-example notebooks on http://readthedocs.io/, but have been running into an issue for codebases which rely on scipy.

You can see a test-case here:
https://github.com/timstaley/nbsphinx-rtd-test
http://readthedocs.org/projects/nbsphinx-rtd-test/builds/

NBSphinx and RTD play well together if your package can be installed into a pure (no-site-packages) virtualenv, but if you try to install Scipy that way you hit an error of error: no lapack/blas resources found. Usually this is no problem - just tick the 'Use system packages' option in RTD settings. The build then goes ahead and almost completes, but fails at the last hurdle; we get to

writing output... [ 50%] demo_notebook
...
File "/home/docs/checkouts/readthedocs.org/user_builds/nbsphinx-rtd-test/envs/latest/local/lib/python2.7/site-packages/pygments/lexers/__init__.py", line 90, in get_lexer_by_name
...
VersionConflict: (setuptools 3.3 (/usr/lib/python2.7/dist-packages),     Requirement.parse('setuptools>=18.5'))

(Full traceback attached:
nbsphinx-rtd-traceback.txt)

So it seems that RTFD has a system-wide ancient version of setuptools which is causing issues for Pygements, when the virtualenv has access to system-packages.

I really wasn't sure where to post this - to your issue tracker or RTFD's - so you may want to bounce it. But it seems like a fairly serious failure case, so I'm hoping you might have a work-around or some suggestions - perhaps trying to build full-dependency notebooks on RTD is a foolish idea from the get-go - should I be trying to pre-generate locally with NBSphinx and just upload the RST's, do you think? Is that something that is already do-able, or I could contribute towards implementing?

I should add, I've actually got this sort of working in an older project - I hacked together a messy conversion script in conf.py, simply shelling out to jupyter nbconvert - which oddly enough seems to work, which is why I was surprised this didn't:
https://github.com/timstaley/voeventdb.remote/blob/master/docs/source/conf.py#L118
Not sure why shelling out works when direct-calls don't, I guess the subshell runs fully in the virtualenv? Probably not of much help for nbsphinx though.

Anyway, many thanks! NBSphinx is great :)

LaTeX build breaks with Sphinx version 1.5

That's because I'm assuming that the whole sphinxVerbatim environment is contained in a single list element in self.body here:

nbsphinx/nbsphinx.py

Line 1162 in 4f50816

lines = self.body[-1].split('\n')

Sadly, sphinx-doc/sphinx#3022 broke that assumption.

Symbolic link causes problems with images in output cells

For example: http://pymc-devs.github.io/pymc3/notebooks/BEST.html
Tries to link to: http://pymc-devs.github.io/pymc3/notebooks/_build/doctrees/nbsphinx/notebooks_BEST_8_0.png

During compilation I get many warnings like:
/home/wiecki/working/projects/pymc/docs/source/notebooks/survival_analysis.ipynb:193: WARNING: image file not readable: notebooks/../_build/doctrees/nbsphinx/notebooks_survival_analysis_11_0.png

I have seen #9 which looks very related and installed from master to make sure #10 was included but those don't fix this issue.

Hide prompt numbering and display headings at right size

Background
I am an R&D engineer at a company called Kitware and I am currently involved in developing an open-source API for the analysis of histopathology analysis that uses ReadTheDocs for providing documentation. We are currently exploring the use of ipython notebooks to create examples for the functionality in our API. After a bit of googling, i found nbsphinx to be a great tool to show ipython notebooks in ReadTheDocs. Once i get a prototype working well, i want to pitch the use of nbsphinx with the rest of the team in our project and also the rest of our company

Issue
Here is rendering of an ipython notebook on ReadTheDocs using nbsphinx. I am currently facing two issues:

• I want to remove the prompt numbering such as In [1], In [2] etc. How do i do this? Is there a metadata field i can set at the notebook level to hide these?
• The section headings are not being rendered at the correct size on ReadTheDocs. However, they render fine on github. Here is my docs/conf.py. Is there a property i need to set here to fix this?

LaTeX: Show plain text output instead of HTML/JavaScript

JavaScript and HTML output cells cannot be displayed in LaTeX, I guess we'll have to live with that.

However, instead of not showing anything, the plain text representation should be shown.

E.g. instead of showing a YouTubeVideo properly in HTML, the LaTeX version should show something like <IPython.lib.display.YouTubeVideo at 0x7f8408056438>.

For the solution of this, filter_data_type might have to be replaced by something that has a separate branch for HTML and LaTeX. See #18 for some information about filter_data_type.

More CSS!

I already posted this on the Jupyter mailing list, but I'm repeating it here:

The current CSS works quite well in modern versions of Firefox and Chrome, as long as the page is wide enough.

Please try it on your browser of choice and submit CSS fixes!

I didn't take all the CSS from notebook/nbconvert/nbviewer, mostly because I don't really understand most of it. Another reason is that the structure of <div> elements is different. nbsphinx doesn't have a
cell containing input and outputs, it only has separate <div>s for each input cell and each part of the output. If you know a better way to do that, please speak up!

If you know more than me about CSS (which is easy), please submit improvements!
Especially if the browser window gets too narrow, my current CSS is not enough ...

Hiding code input but not output?

The documentation has a nice discussion of how to hide code cells and their output entirely. It is however also frequently useful to hide just the code and not the output for some or all code-cells in a notebook (e.g. to make an HTML only report). I've seen some rendered html that seems to go further by offering code-folding buttons on the rendered html.

Is there a way to hide just the code input but not the output with nbsphinx? For reference, with jupyter's nbconvert one can use templates and a command as such:

jupyter nbconvert your_notebook.ipynb --to html --template output_toggle_html

where the template is like the one adapted from this SO answer

Support images with raw html syntax

There is some background discussion in this Jupyter notebook issue, but the gist of the issue is that nbsphinx currently doesn't recognize images declared e.g. as

<img src="images/dashboard_files_tab.png" width="791px"/>

only ones that use the plain markdown syntax:

![alt](images/dashboard_files_tab.png)

This obviously precludes passing (useful) things like custom size hints. I don't know if this is easy to fix in nbsphinx itself or if there's an underlying tool (say pandoc) that does the heavy lifting with the files... But I figured I'd mention it, it would help us use whichever syntax is more sensible in a given setting.

For now, for Jupyter we'll work around it in our docs by limiting ourselves to the ![..](..) syntax.

LaTeX: warning ("unusable reference target found") for local file links

Links to local files work fine in HTML, but they can obiously not work in LaTeX.
Those broken links should still somehow look like links in the PDF and the warning message should be somehow avoided.

See also http://stackoverflow.com/questions/18560042/hyperlink-to-an-external-git-repository-in-sphinx-pdf-documentation