[DOC] add source code to rendered docs

[hwine]

This would help during test development and selection. (Related to #387.)

Figure the "best" way to utilize Sphinx extensions to include the display the way we prefer. If folks have ideas about how that code should be laid out, please leave it below.

[hwine]

One choice we have is "How should the source entries appear in the table of contents?"

• link to source-by-section (e.g. frost, aws, ...) on main ToC
• Just link to a source sub-section, where each section has it's own links
• Differentiate between "tests" and "support code" (client.py, conftest.py) under the assumption that frost users don't need to know about those. (Should be possible, but I'm currently having trouble with the config)
• put support code under a "contributing/development" section.

I'll be experimenting with these on my doc test site - ping me on slack if you want a choice added, or done sooner.

[sciurus]

It's a little hard to visualize just based on the descriptions- can you screenshot some different options?

[hwine]

It's a little hard to visualize just based on the descriptions- can you screenshot some different options?

Even better -- I'll (slowly) get all the options "live" on the test site, as I think clicking may be needed to make the best decision.

My intent was just to get folks thinking about things at this point, and solicit options I haven't thought of. I'll flag the PR for review by everyone when all the choices are up.

[hwine]

"test site" is up at https://hwine.github.io/frost/ -- there are some serious challenges:

• much of the test_*.py does not render cleanly using sphinx-apidoc, as the modules do not import cleanly in the context of building the docs.
• that might be helped by switching to the "autodoc" mode, which parses instead of importing
  • "autodoc" would make "extraction of just tests" harder, as we'd have to write a filter function

My gut feel is that we should abandon the options, and do the simplest thing-that-works for now. If other SRE teams want to use frost, the investment in "better" may be warranted.

vote by reaction, please: @ajvb @g-k @sciurus @Micheletto and anyone else. [this approach abandoned, as requiring too much customization at this time.]

[hwine]

We'll finalize api-docs-for-now in the PR.