How to handle notebook-level metadata

executablebooks / MyST-NB

Parse and execute ipynb files in Sphinx

https://myst-nb.readthedocs.io

BSD 3-Clause "New" or "Revised" License

207 stars 83 forks source link

How to handle notebook-level metadata #81

Open choldgraf opened 4 years ago

choldgraf commented 4 years ago

In a markdown file, this is pretty straightforward - it's just the --- blocks at the top.

But for an ipynb file, we have a couple options:

Use all keys in the notebook metadata
Use a special key meant for myst-nb
Use a front-matter cell of some kind (raw cell, or check the first markdown cell for YAML?)

Currently we do the first, just wanna make sure it's an intentional decision!

chrisjsewell commented 4 years ago

Note the first option makes markdown-notebook conversions simpler. Also note, when converting to the docutils docinfo, currently all values that are lists or dicts are stripped (e.g. {"key": {"nested": "dict"}})

https://github.com/ExecutableBookProject/MyST-Parser/blob/8b0d16e50c0a376810c751400831d59c20193d1a/myst_parser/docutils_renderer.py#L1227

choldgraf commented 4 years ago

yeah - I think it makes parsing things simpler, but at the cost that asking users to manipulate notebook metadata is trickier, since IMO there isn't a very user-friendly UI process around this.

Do you think it would add much complexity if we parsed the first markdown cell, checking for front-matter YAML, and added that to whatever the notebook-level metadata had in it?

chrisjsewell commented 4 years ago

That’s certainly a possibility