Update documentation

[tjfulle]

General changes:

• be expanded to document use cases not currently documented
• reorganized to reflect the source layout. Eg, plugins should be documented separately from canary-core
• document resource set behavior, see Relationship between resource pool and hpc_connect resources #47 . The documentation should unfold in two parts: canary-core docs describe the resource pool and how to set it. canary-hpc describes how hpc_connect takes over resource set behavior in batched runs.

Specific changes:

• User defined test generator modified to reflect .pyt is the main file type and that others can be defined in plugins.
• SubCommand example needs to change email method name to execute
• Move Extend canary with plugins info into extending.rst index page
• Move .vvt specific docs (including directives) into canary_vvtest
• Remove .vvt specific mentions from directives page (they should be moved to vvtest plugin docs)
• add resource pool schema to resource pool docs
• update time resources doc to reflect update API and command line flags
• update config scopes (use bullets to show precedence)
• configuration sections doc needs intro
• add intro to reporting section
• consider removing plain text output for reports and replacing with screenshots
• double check that all plugin hooks are present. better, the plugin hooks docs should be autogenerated
• ctest docs before cmake (more commonly used)
• getting help: has several subcommands -> has many subcommands
• add more examples in the usage section that correspond to directives not documented.

[danielsjensen1]

@tjfulle I just ran into the canary_generator to canary_testcase_generator name change after updating a custom canary plugin. I think the documentation probably needs an update for that as well.

[zseckert]

I'm not sure if this is a documentation issue or a small bug, but the docs point to using CANARY_PLATFORMS environment variable, but _canary/when.py checks CANARY_PLATFORM. If the docs are right and the code is wrong, and you'd prefer I make a PR, just let me know.

Additionally, a specific usage that doesn't have an explicit example (at least that I could find) was when="parameters=". It is mentioned in many of the directives but figuring out the actual formatting for the string or dict took some experimentation.