Sort of continuing the discussion from Theme Standardization Through "Feature" Support and Where would you recommend putting documentation for a theme?:
The hugoThemes encourages theme developers to create the exampleSite directory and I can see where some have have done that with heavily commented config.toml files.
Is that the best way to approach this? Reading Derek’s PR for the social structure got me to wondering about that (again).
I would say that the exampleSite should be avoided if possible. Some of the @digitalcraftsman themes are so “custom” that it makes sense (we would not be able to build a demo without it) – but it doesn’t help us in the ultimate goal of portability.
If themes are very simple with self-explaining config files there will might be no need to create an exampleSite folder.
However, as @bep already mentioned, some themes are much more complex and offer much options for customizations. In general, I try to add concise comments in the config file. In the README I have a more detailed setup guide for a theme.
If themes are even more complex I add the documentation to the exampleSite directory and link to the demo site - for the Material docs theme it serves a double pupose.
How you document your theme is mostly depended on how customizable your theme can be.