Use "title" instead of "name" for metadata to match the notebook format

[m-rossi]

The notebook format has a metadata field for the "title" of the notebook: https://github.com/jupyter/nbformat/blob/master/nbformat/v4/nbformat.v4.schema.json#L63
I think it should be used instead of the field "name".

[takluyver]

Changing this would effectively be breaking API, because separately developed exporters and templates can use the resources dictionary.

[mpacer]

There's a version of this that can be done… specifically the html and slides templates could have this change in the vein of #672…

Though the logic needs to be richer to handle the case where the title is not set… as can be seen in that PR, e.g.,:

nbconvert/nbconvert/templates/latex/base.tplx

Lines 143 to 149 in 5c0279a

	((* block title -*))
	((*- if "title" in nb.metadata *))
	\title{((( nb.metadata.get("title", "") | ascii_only | escape_latex )))}
	((*- else *))
	\title{((( resources.metadata.name | ascii_only | escape_latex )))}
	((*- endif -*))
	((*- endblock title *))

[m-rossi]

We could add some code to ensure compatibility to metadata containing "name" (e.g. copy it to "title")? Then we could match the notebook format.

[mpacer]

No… we shouldn't overwrite the current logic of name, better is to change the logic of the template itself.

As @takluyver pointed out, there is an implicit API that we should be hesitant to change, so anything that we can do that instead works entirely inside templates is going to be safer.

This problem can be addressed in the templates, so let's go with that option.

[mpacer]

Re: the format, technically the name and the title are different kinds of things. We just have used the name as though it were the title in nbconvert… There is no guarantee that the title is present in a notebook, it's just an option and we shouldn't overwrite notebooks to have a title when they don't.

Here's a model of why this would go wrong:

Suppose someone ran nbconvert in-place while their notebook was named notebook_a.ipynb with no title metadata. If we were to assign the metadata as part of our run, then that notebook would now have a title field with notebook_a as the title. But what if the person then changed their notebook filename to be notebook_b.ipynb… because we assigned the metadata from before, when they exported, the title "notebook_a" would be carried around with it. The person never put that metadata there, so they might have no idea where to begin debugging to figure out why their titles don't change with their filename (the currently expected behaviour).

[m-rossi]

Ah, understood. I will look into the templates tomorrow.

[mpacer]

This is almost correct, but it's actually in the notebook metadata itself, not in the resources metadata. So, the call would be if nb.metadata.get("title","") rather than if 'title' in resources['metadata'], as it shouldn't be there redundantly with the notebook's title metadata.

[mpacer]

Also, even cleaner might be to set a variable to either of the values (using an or) and then to reference that variable in a single (non-conditional) line in the template.

That'd be cleaner for the other LaTeX version as well.

[m-rossi]

Ah, I mixed up those two metadata dicts. Thanks!

For your second recommendation you mean using nb.metadata.get('title', '') or resources['metadata']['name']?

[mpacer]

Yes something like set nb_title = nb.metadata.get('title', '') or resources['metadata']['name'] which you can then use in the lines that follow to simplify their display logic.

[mpacer]

@m-rossi I thought we had implemented examples of that already in our templates and in searching, I'm seeing that we hadn't. Are you running into any issue implementing that logic? I'm happy to help out if you are — Jinja can be weird sometimes around logical constructs & I have some ideas if that does not work in a straightforward way.

[m-rossi]

Sorry for the delay, I've just added the few lines.
As you said, there is no example of a set statement in the templates. Therefore I added the set-statement at the top of the document, is this the way you want the templates to look like?

[mpacer]

I think it’d be better to have it local to the block just to keep the logic local. But it’s not a big difference. I can either merge this or wait for you to make the change, which would you prefer?

[m-rossi]

No problem, I've just moved the lines.

[mpacer]

Beautiful! Merging! Many thanks!