Add options for inputs, outputs and prompts to be excluded

[DavidPowell]

Resolves #131. Code was contributed by @keluc.

Currently no changes have been made to the docs to reflect the additional options.

[mgeier]

Thanks for this PR!

Is exclude_code_cell really ever needed?
And even if that's the case, wouldn't a combination of exclude_input and exclude_output do the same thing?

Is exclude_markdown really needed?
What would be a use case for that?

[keluc]

Matthias, no particular reason. I had taken up the several options that were available that I wanted to use/test out (Apparently I didn't implement 'exclude_raw').

[DavidPowell]

For my particular case, I only use the nbsphinx_exclude_input and nbsphinx_exclude_output_prompt options. I could also envisage that nbshinx_exclude_input_prompt might be useful.

In all other cases (hiding entire code or markdown cells or hiding input) if I ever wanted to do this, it would be on a per-cell basis by creating tags, and using the new tag based element filtering feature of nbconvert.

Unless anyone can point to a use-case that requires other options, I think it best to go with just the 3 options mentioned above.

Should I just add another commit to remove unwanted options, I would you prefer that I rebased and squashed to remove them from the history?

[rddaz2013]

That means the "hide_cell" option is not a function of nbsphinx - nbconvert/sphinx is doing the job?

I had implemented it via the templates.
master...rddaz2013:master

[DavidPowell]

@rddaz2013 I take it that your preferred option is to hide individual input cells, based on metadata created by the Jupyter nbextension hide_input. The current implementation gives an option to show or hide all cells, which is good enough for my purposes. Does your use case require hiding only specific inputs cells?

In my view, hiding individual inputs and outputs would be better done with nbconvert's new feature, tag based element filtering. This would avoid the need for any custom templates, doesn't require any extensions and the same approach can be used in other contexts, e.g. using nbconvert to directly generate html.

[mgeier]

@DavidPowell I agree, can you please just add the options you need? If somebody else needs more, we can add them later.

would you prefer that I rebased and squashed to remove them from the history

Normally I would prefer a rebase+squash, but in this case I think it would be good to keep @keluc's commits, because he first took the initiative.
But I guess you could still re-base without losing the original authorship.

[DavidPowell]

Unwanted options have been removed. As I didn't get any feedback from @rddaz2013 on what he means by hiding cells, nothing has been done on that front.

[mgeier]

nbsphinx_exclude_input_prompt doesn't seem to work.

nbsphinx_exclude_output_prompt removes the output prompt but an awkward space remains (in LaTeX it seems to be the width of one character, in HTML it is the whole prompt width).
Is this intentional?

[tshead2]

From what I can see here, exclude_input_prompt isn't used by the new code. I'm chiming in because I write lots of library documentation using notebooks, and the input prompts are meaningless distractions in that case. See http://toyplot.readthedocs.io/en/stable/tutorial.html for an example of a notebook without prompts on RTD (generated with my own home-grown code, which I'd like to eliminate in favor of nbsphinx).

[keluc]

I've taken a further look, because in the standalone use of nbconvert it all seems to work (exclude_input_prompt etc.), but in this context this doesn't always work.

• I already had an issue with the exclude_output_prompt which wasn't always excluded (not further investigated). I handled this by amending the run method in the class NbOutput, see my comments in the beginning of this discussion . I think we have the same problem in NbInput.run method. We can apply the same approach.
• With respect to the awkward space, it seems to me that it also can be handled in the same piece of code of both run methods, by only adding to the container variable if we want to show the prompts.
• With respect to the latex issue, in the same run method, there is a line of code
  latex_prompt = text + ' ' which may cause this problem (not checked)

To me, the reason why we can't use the options of nbconvert to it's full potential has to do with this approach (NbInput.run and NbOutput.run). The following resolves both issues (latex issue still to test)

class NbInput(rst.Directive):
 ...
    def run(self):
    ...
        # Input prompt
        if self.state.document.settings.env.config.nbsphinx_exclude_input_prompt:
            text = ''
            latex_prompt = ''
        else:        
            text = 'In [{}]:'.format(execution_count if execution_count else ' ')
            container += CodeNode.create(text, classes=['prompt'])
            latex_prompt = text + ' '
...

and

class NbOutput(rst.Directive):
....
    def run(self):
    ....
        # Optional output prompt
        if execution_count:
            if self.state.document.settings.env.config.nbsphinx_exclude_output_prompt:
                text = ''
                latex_prompt = ''
            else:
                text = 'Out[{}]:'.format(execution_count)
                container += CodeNode.create(text, classes=['prompt'])
                latex_prompt = text + ' '
        else:
            # Empty container for HTML:
            container += rst.nodes.container(classes=['prompt', 'empty'])
            latex_prompt = ''
...

[mgeier]

@tshead2 Thanks for your input! It's really helpful that you show an actual example of what you want to achieve. I don't really see a problem in showing the prompts, though. You are telling your readers that you are using notebooks (and you even urge them to play around with them), so I don't see why it should be helpful to try to hide the fact that your code snippets are actually Jupyter notebook cells.

Having said that, you can actually hide the prompts in the HTML output by using:

nbsphinx_prompt_width = 0

Since that only does some CSS manipulations, it doesn't have any impact on the LaTeX output.

[UPDATE (April 2020): Please don't use nbsphinx_prompt_width to hide prompts. This will break when #439 is merged. For a more reliable (CSS-based) alternative see https://nbsphinx.readthedocs.io/en/latest/custom-css.html]

[tshead2]

@mgeier - Happy to butt-in! When it comes to running notebooks, I appreciate the prompts for keeping track of the order in which I've (re)run cells. For documentation, where the order is always linear, they may be confusing for non-notebook users, provide no useful information for notebook experts, consume space, and add visual noise. Anyway, that's good news about nbsphinx_prompt_width ... I don't see it in the documentation, where should I be looking for that?

While I'm at it, I'll also put in a good word for occasionally hiding cell inputs. I sometimes need to generate a plot to illustrate an idea, and I want the reader's focus to be on the plot, not the code used to create it.

Cheers,
Tim

[mgeier]

@tshead2

I don't see it in the documentation, where should I be looking for that?

The most reliable source is the source.

All options are (and future options will be) visible in the setup() function near the bottom of the file src/nbshinx.py:

nbsphinx/src/nbsphinx.py

Lines 1438 to 1448 in 20621a3

	app.add_config_value('nbsphinx_execute', 'auto', rebuild='env')
	app.add_config_value('nbsphinx_kernel_name', '', rebuild='env')
	app.add_config_value('nbsphinx_execute_arguments', [], rebuild='env')
	app.add_config_value('nbsphinx_allow_errors', False, rebuild='')
	app.add_config_value('nbsphinx_timeout', 30, rebuild='')
	app.add_config_value('nbsphinx_codecell_lexer', 'none', rebuild='env')
	# Default value is set in builder_inited():
	app.add_config_value('nbsphinx_prompt_width', None, rebuild='html')
	app.add_config_value('nbsphinx_responsive_width', '540px', rebuild='html')
	app.add_config_value('nbsphinx_prolog', None, rebuild='env')
	app.add_config_value('nbsphinx_epilog', None, rebuild='env')

All of these options (unless I missed some) are also mentioned in the file doc/conf.py:

nbsphinx/doc/conf.py

Lines 22 to 82 in 20621a3

	# Execute notebooks before conversion: 'always', 'never', 'auto' (default)
	#nbsphinx_execute = 'never'
	# Use this kernel instead of the one stored in the notebook metadata:
	#nbsphinx_kernel_name = 'python3'
	# List of arguments to be passed to the kernel that executes the notebooks:
	#nbsphinx_execute_arguments = ['--InlineBackend.figure_formats={"png", "pdf"}']
	# If True, the build process is continued even if an exception occurs:
	#nbsphinx_allow_errors = True
	# Controls when a cell will time out (defaults to 30; use -1 for no timeout):
	#nbsphinx_timeout = 60
	# Default Pygments lexer for syntax highlighting in code cells:
	#nbsphinx_codecell_lexer = 'ipython3'
	# Width of input/output prompts used in CSS:
	#nbsphinx_prompt_width = '8ex'
	# If window is narrower than this, input/output prompts are on separate lines:
	#nbsphinx_responsive_width = '700px'
	# This is processed by Jinja2 and inserted before each notebook
	nbsphinx_prolog = r"""
	{% set docname = env.doc2path(env.docname, base='doc') %}
	.. only:: html
	.. role:: raw-html(raw)
	:format: html
	.. nbinfo::
	This page was generated from `{{ docname }}`__.
	Interactive online version:
	:raw-html:`<a href="https://mybinder.org/v2/gh/spatialaudio/nbsphinx/{{ env.config.release }}?filepath={{ docname }}"><img alt="Binder badge" src="https://mybinder.org/badge.svg" style="vertical-align:text-bottom"></a>`
	__ https://github.com/spatialaudio/nbsphinx/blob/
	{{ env.config.release }}/{{ docname }}
	.. raw:: latex
	\vfil\penalty-1\vfilneg
	\vspace{\baselineskip}
	\textcolor{gray}{The following section was generated from
	\texttt{\strut{}{{ docname }}}\\[-0.5\baselineskip]
	\noindent\rule{\textwidth}{0.4pt}}
	\vspace{-2\baselineskip}
	"""
	# This is processed by Jinja2 and inserted after each notebook
	nbsphinx_epilog = r"""
	.. raw:: latex
	\textcolor{gray}{\noindent\rule{\textwidth}{0.4pt}\\
	\hbox{}\hfill End of
	\texttt{\strut{}{{ env.doc2path(env.docname, base='doc') }}}}
	\vfil\penalty-1\vfilneg
	"""

Most of the options are also mentioned in the documentation notebooks, but for some of them I was too lazy to mention them.

If you want to help out, please make a PR (or multiple) with improvements!

[OverLordGoldDragon]

Needed feature, any plans to merge?