docs: Prototype docs examples doubling as tests

[lgritz]

New theory of code examples in the docs: every one should live in the testsuite somewhere, and merely be included by reference in the docs. This ensures that every code example works, stays current with the evolution of the APIs, and never breaks. It also beefs up our test cases for more thorough code overage in the testsuite.

I've done this with just two examples here, but hopefully it serves as an example for others to -- bit by bit -- convert all the other code examples in the docs into tests in a similar manner.

Doing this for any one example is a perfect "good first issue," since it's bite sized and can easily be done in a day, it doesn't require any knowledge of deep OIIO internals, and in the process it also teaches you something about how both the docs and the testsuite are set up.

A few notes:

• I'm structuring it (for now?) as two testsuite entry for each chapter of the documentation (one for C++ and one for Python).

• Note how I can have many code snippets in a test source file, and use the Sphinx :start-after: and :end-before: modifiers of literalinclude to clip particular subsections of the file, using special comment markers in the code.

While I was there, I also fixed some typos I noticed in the text of the chapter, oops.

[grdanny]

any reason not to do the BEGIN here above the import in line 31?
It reads really nice and clean in the doc when it has the imports and the ImageSpec and all.

[lgritz]

For this example, I merely replicated as close as possible the appearance that was in the docs previously for that code. In the case of this second example, it was just a snippet of a few lines, so that's what I blocked off with the BEGIN/END markers.

If you read that section of the docs, you'll see that the way I wrote it initially is structured as first showing a complete but very simple example of writing an entire image, and then as it discusses each additional topic (how to write individual scanlines, how to write a tiled image, how to add an attribute the metadata, etc.), it only shows the few additional lines that implement that topic of that discussion, leaving it to the reader to understand (it's pretty simple) where those additional lines go in the context of the original example.

Whether that's a good pedagogical approach, I suppose, is a matter of debate.

So this is an open question I wondered about at the time I did this and would appreciate opinions on:

Should our policy be that EVERY code example appearing in the docs be a fully run-able section of code? Say, at a minimum, a syntactically correct Python function? Or even a fully correct program that can be run with no other context? That's a little more verbose, but does have the advantage of ensuring that every example is complete and requires on inference about what might be required before or after.

[grdanny]

Ah - I see, matching what was there before certainly makes sense.
And yes, it makes total sense in the context of the entire doc.

I don't think you want to put such a hard restriction of making EVERY code example fullly run-able.
It can be whatever makes the best sense for each page and subject.

In this case, since you do have a nice fully runnable example at the top. It makes sense that the rest is shorter and cuts to the chase of the feature you are showcasing.

Mostly I was curious because now that it's a test, the fully runnable code is right there in front of us (and we know that it runs) so it was tempting to reach for it and include the whole thing.