docdeep (#842)

Why write documentation when you could make yet another documentation
generator?

I like the *idea* of Doxygen -- generate documentation by extracting the
comments in code, particularly those explaining the individual functions
or methods that are part of an API. But Doxygen, ick. Its markup
conventions make the code comments themselves hard to read, and the
output HTML is...  not very aesthetically pleasing (to me, at
least). And it's really a kitchen sink package, a lot of baggage to
carry along for the 2% of it that I really want.

On the other hand, I just love Morgan McGuire's awesome Markdeep
package (https://casual-effects.com/markdeep/), which is an extension
of Markdown but adds a crap ton of neato features that are great for
code, math, and diagrams.

So I tried my hand at doing something really small and "good enough" to
let you mark up your code comments -- but MINIMALLY, so subtly that the
casual observer might not even notice, and using markdeep for anything
fancy -- and then extract that material to generate Markdeep-based
documentation pages that look beautiful.

So here is the prototype. The entire implementation is just one Python
script, src/build-scripts/docdeep. In addition to documenting itself,
I also used oslquery.h to test the idea, so you can see both how the
docdeep markup looks in code, and as well, now we finally have OSLQuery
class documentation, which we never had before. Ha! Those two pieces
of documentation are generated automatically as part of the OSL build, so
you can see what we did on the CMake side to make that happen.

To see how you use it in source, look at oslquery.h.
(Better to just look at the new oslquery in toto, rather than trying to
understand just the diffs of this patch.)

To see what the resulting docs look like, build OSL and look at the
resulting share/doc/OSL/OSLQuery.md.html in your browser.

This is still experimental. I expect it to undergo a lot of revision.
When it settles down, if this looks useful to people and there is
demand, I might split this off into a separate open source project (just
the docdeep script) so that people can use it for other projects without
the overhead of downloading and building OSL. Let's see how it goes.

Feedback appreciated.

Author: lgritz