Support extending nbsphinx-rst.tpl

[adrn]

Over in astropy/astropy-tutorials, we'd like to add a link to the bottom of each sphinx page generated from a notebook (and only these) that contains a link to the source notebook on github. Maybe there is an easier way, but my initial thought was to add a new section to the jinja template that generates the page. But, it looks like that is hard-coded into nbsphinx.py as a string. If nbsphinx was restructured into a package, I think it could support custom .tpl files as well via an, e.g., nbsphinx_custom_tpl option in conf.py. I tried to spec this out on my own fork of nbsphinx, but got stuck on paths (trying to get the custom template to know about the nbsphinx template, and to get nbsphinx to find the custom template in, e.g., the _static path of the sphinx source directory). Any thoughts or ideas on this? Thanks!

cc @eteq

[mgeier]

Thanks for the suggestion!
I would also like to have a way to include links to the source notebook on Github, see #5.
I've tried to work into this direction with sphinx-doc/sphinx#2399 and sphinx-doc/sphinx#2454.
At some point I also wanted to extend this with an option to provide an arbitrary base URL (e.g. for Github), but it seems that I never got to it ...
I've laid out my ideas in a message to the Sphinx mailing list (https://groups.google.com/forum/#!topic/sphinx-dev/q8dGyV6dN4A), it would be great if you want to follow up on this!

Regarding the template files, I'd prefer not to expose those too much, because I would like to get rid of them in the long run. I still hope that at some point we can realize #36, and with that the template-based converter will have to go.

Having some other mechanism to put content to the top or the bottom of the page would be great though, probably something similar to rst_prolog and rst_epilog (http://www.sphinx-doc.org/en/stable/config.html#confval-rst_epilog)?

[mgeier]

@adrn I've just released version 0.3.0, which includes the options nbsphinx_prolog and nbsphinx_epilog. Do those options allow you to do what you need?

[adrn]

Ah yes, this looks like it would work for what we needed! I think it would still be worth thinking about allowing custom templates, but that is a low priority request... Thanks!

[mgeier]

I'm leaning against allowing custom templates, because I'm planning to switch away from a template-based converter in the long run.

[ajp619]

I've been thinking about custom templates as well. I'd like to be able to hide cell input by modifying the input block to:

{% block input -%}
{%- if cell.metadata.hide_input -%}
{%- else -%}
.. nbinput:: {% if cell.metadata.magics_language -%}
{{ cell.metadata.magics_language }}
{%- elif nb.metadata.language_info -%}
{{ nb.metadata.language_info.pygments_lexer or nb.metadata.language_info.name }}
{%- else -%}
{{ resources.codecell_lexer }}
{%- endif -%}
{{ insert_empty_lines(cell.source) }}
{%- if cell.execution_count %}
    :execution-count: {{ cell.execution_count }}
{%- endif %}
{%- if not cell.outputs %}
    :no-output:
{%- endif %}
{%- if cell.source.strip() %}

Seems like this would be easy to do if I could write a custom template that extends nbsphinx-rst.tpl and put it in the _templates directory(?) but I'm struggling with the same issue as @adrn.
Any thoughts on the best way to do this?

[mgeier]

@ajp619

The template-based exporter is just an implementation detail of nbsphinx. And it will be removed once #36 is implemented.

Regarding hiding cell inputs, please see #65, #86 and #185.