Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add options for inputs, outputs and prompts to be excluded #185

Open
wants to merge 4 commits into
base: master
from

Conversation

@DavidPowell
Copy link

DavidPowell commented Apr 27, 2018

Resolves #131. Code was contributed by @keluc.

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

keluc and others added 3 commits Oct 7, 2017
Added nbsphinx options
"self.state.document.settings.env.config.nbsphinx_exclude_output_prompt"
instead of a extra global variable
@mgeier

This comment has been minimized.

Copy link
Member

mgeier commented Apr 27, 2018

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

This comment has been minimized.

Copy link

keluc commented Apr 27, 2018

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

This comment has been minimized.

Copy link
Author

DavidPowell commented May 1, 2018

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

This comment has been minimized.

Copy link
Contributor

rddaz2013 commented May 1, 2018

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

This comment has been minimized.

Copy link
Author

DavidPowell commented May 1, 2018

@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

This comment has been minimized.

Copy link
Member

mgeier commented May 3, 2018

@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.

…ions, since no clear use case has been shown to date.
@DavidPowell

This comment has been minimized.

Copy link
Author

DavidPowell commented May 8, 2018

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

This comment has been minimized.

Copy link
Member

mgeier commented May 9, 2018

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

This comment has been minimized.

Copy link

tshead2 commented May 29, 2018

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

This comment has been minimized.

Copy link

keluc commented May 30, 2018

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

This comment has been minimized.

Copy link
Member

mgeier commented May 30, 2018

@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.

@tshead2

This comment has been minimized.

Copy link

tshead2 commented May 30, 2018

@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

This comment has been minimized.

Copy link
Member

mgeier commented Jun 2, 2018

@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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.