Yeah, the documentation needs a lot of love.
My responses might not be 100% correct, but here goes:
* What causes SS to load a particular .ss file for a given page. I know that in the page controller's index function I can call renderWith("templatename"), but how does SS know where to find the file? Is it always under mysite/templates?
Basically, lets take an example page type, called "ArticlePage". An ArticlePage extends Page.
SilverStripe renders the page like this:
1. Look for templates called ArticlePage.ss in the theme templates directory. So, if your theme is set as 'blackcandy', it looks for 'themes/blackcandy/templates/articlepage.ss'
2. If it can't find it, it will then look for 'articlepage.ss' in the templates folder in the same folder tree as the atriclepage.php. Ie, for the page 'mysite/code/articlepage.php' it will look for 'mysite/template/articlepage.ss'
3. If it can't find, it repeats the process for subsequent class inheritances - ie, it will look for '/themes/blackcandy/templates/page.ss', then '/mysite/templates/page.ss'
When you use renderWith(), SilverStripe will go find your template using a similar scheme as above (ie, try the themes folder first).
This is clever, because then you can create themes (in the themes dir), but also create templates specific to the project (in your project dir), or even apply templates programatically (with renderWith())
* While we're on the subject, how does SS know to look in the mysite folder? Is that hardcoded, or can I change it?
It's just the folder with your _config.php file in it. You can change 'mysite' to 'bananamonkey' if you like, your site will still work exactly the same (after you have done a db/build?flush=1)
* What is the effect of calling SSViewer::set_theme()? in _config.php, and when is _config.php loaded? Is it only at database re-build time?
It just tells SilverStripe where to look *first* for template files. It doesn't effect your database, just the cached output files and subsequent rendering.
* What is the significance of the 'Layout' folder in the default blackcandy template? I notice a $Layout in the page.css in blackcandy/templates, but I thought that this would call a function on the page's class. Can it also invoke another template in the layout folder?
Yes.
The layout are just like page templates but for smaller snippets of the page. For example, You could create a 'articlepage.ss' layout template (in the layout folder) - and NOT have an 'articlepage.ss' page template (in the templates folder). When building the page, SilverStripe will render the PAGE with the page.ss template, and the LAYOUT section with the articleholder.ss template.
Does this help, or is it just confusing? :D