docs tutorial text on guarded and logging is misleading

[mpounsett]

The tutorial text in check_users.rst states that if the main() function is decorated with @guarded that the logging module gets configured before the function starts. This can be misleading, because it can easily be read to apply to the module-level main() function, when in fact it applies to the check.main() function.

This section of the documentation should be reworded to make that clear. If, for example, logging messages were inserted anywhere inside the module-level main() function, they would not be covered by this configuration. Even setting the verbose= argument to @guarded would have no effect on the module-level main(), because the logging configuration doesn't take effect until Runtime.execute() is called (as a side-effect of check.main()).

_log = logging.getLogger('nagiosplugin')

@nagiosplugin.guarded
def main():
    argp = argparse.ArgumentParser()
    argp.add_argument('-v', '--verbose', action='count', default=0)
    args = argp.parse_args()
    _log.info("This does not follow args.verbose setting")
    check = nagiosplugin.Check(Logging())
    check.main(args.verbose)

It's worth noting in the documentation that a workaround exists:

_log = logging.getLogger('nagiosplugin')

@nagiosplugin.guarded
def main():
    argp = argparse.ArgumentParser()
    argp.add_argument('-v', '--verbose', action='count', default=0)
    args = argp.parse_args()
    runtime = nagiosplugin.Runtime()   # get a copy of the singleton
    runtime.verbose = args.verbose
    _log.info("Now follows args.verbose setting")
    check = nagiosplugin.Check(Logging())
    check.main(args.verbose)

There seems to be insufficient discussion of @guarded and the Runtime singleton in the docs generally, so there might be a wider improvement to be made as well.