Configuration documentation should have a section that focuses on templating workflows.

[mpacer]

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.

[takluyver]

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.

[mpacer]

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)

• the distinction between local versions of jupyter_config.py vs. jupyter_notebook_config.py vs. jupyter_nbconvert_config.py
  • this includes explaining whether it will apply to everything vs. the "Download as…" menu option in the notebook vs. command line use of jupyter nbconvert
• highlighting the distinction between tplx and tpl and the advantages of using extension free template file names
• explicit common use cases (e.g., hiding prompts, hiding input, hiding output, &c.)
• linking to the most commonly asked for features that are not going to be incorporated into nbconvert itself (e.g., python-markdown and embedhtml)
• best practices for writing templates (e.g., not using super() in LaTeX templates if you want to change the use packages and a list of the packages that are most likely needed by most export utilities
• examples of how to change small things (like font sizes, font faces, &c.) for different publication output formats

[mpacer]

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.

[mpacer]

#554 took care of some of this.

[chrisjsewell]

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:

1. non-trivial to understand the full conversion process (having to go through the inheritance tree to find where particular methods have been implemented/overriden)
2. difficult to swap in/out multiple rules

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.