In conjunction with Location demotion and PVSystem/LocalizedPVSystem/ModelChain addition but now as separate issue:

The Ipython Directive could be used.

I'm using it in the new docs, so I don't understand why you're saying this.

I think the original intention with notebooks was to offer quick interactive exploration.
But now we find it hard to keep them updated and tested.
Below a way which might help

• integrate the notebooks into testing, tools: RunNotebook, see also [yt-dev] Documentation and Testing
• update and enhance the documentation to include the features of Location demotion and PVSystem/LocalizedPVSystem/ModelChain addition #93
• add system modelling tutorial, as in Tutorial: system modeling #84 but adapted to the changes in Location demotion and PVSystem/LocalizedPVSystem/ModelChain addition #93