Open mpacer opened 7 years ago
Here's the config overview page. I don't want to duplicate this explanation in every project that uses our config system, but we should certainly link to it from the nbconvert config options page.
'Docs need extra work' is something that's probably always going to be true.
NBconvert has a different kind of use case for customisation and configuration to the point where it is useful to have an encapsulated document that describes how people can locally create templates that give them the exporting utilities that they want. Ease of output customisation is currently one of the biggest advantages that rmarkdown over our current conversion machinery. This is as much due to the fact that they have a basic model of a document that carries with it specific formatting instructions (rather than a record of an interacting programming environment that can be converted into nice documents) but anything we can do to bridge that gap.
This would include (making a checklist for myself)
jupyter_config.py
vs. jupyter_notebook_config.py
vs. jupyter_nbconvert_config.py
jupyter nbconvert
tplx
and tpl
and the advantages of using extension free template file names Some of this should probably be included under https://nbconvert.readthedocs.io/en/latest/customizing.html but I'm worried about adding too much there as it's already a decently intimidating page for those who aren't already familiar with applying templates to structured documents.
hey again @mpacer! This is exactly the issue I came across for creating custom .tplx, as explained here in ipypublish . I found that the inheritance based system made it:
So I have written a simple pluginesque system in create_tplx.py to build up the template from 'fragments' (packages, definitions, etc). I'm sure it could be improved but, personally, I find this a lot easier.
It is remarkably difficult to find a clean explanation about how to create and use a local configuration file.
At best it's split across a bunch of places, at worst it's incomprehensible from the perspective of someone who doesn't already know most of what they're looking for.