Thoughts on way to set environment?

[henryiii]

One thing I realized in implementing #74 in docs is it's really handy to be able to set the environment - specifically, pop the NO_COLOR variable and push the FORCE_COLOR (or PYTHON_COLORS, but the later is more general). You can do it apparently inside conf.py, but that might have side effects, like affecting logging output. You can also do it in a task runner like nox. Those are fine for now, but maybe it could be improved. Thoughts:

Maybe the config setting could set these for you? Enabling ANSI but then getting different doc outputs based on the value of NO_COLOR could be problematic. And since this isn't a terminal, FORCE_COLOR is usually needed to use it.

Or maybe there could be either a config setting or a local setting to manually set environment variables? Ideally this would also support removing variables like NO_COLOR (which doesn't have a set-to-empty check according to the standard!).

Or maybe both, a default plus a way to set variables.

[jamadden]

I definitely don't want to mess with the user's environment variables without express written consent. Doing otherwise could be surprising.

The most flexible thing to do would be to define a configuration value, programoutput_environment that, in conf.py, the user would set to their desired environment. They could start with a copy of os.environ and mutate it, or they could build something up from scratch. It would default to None, meaning we'd pass os.environ to Popen, but if it was set, we'd pass it instead. This seems fairly straightforward to implement.

Naturally that would affect all program-output/command-output directives the same way. I don't see a graceful way of adding directive-specific behaviour: you'd have to use at least three options, one to unset values and one to set them and one to say whether or not to include other values from the existing environment, and then you have to define rules and parse the "set" directive into an environment dict. Not pretty, more complicated to implement and more complicated to read.

.. program-output:: some --comand
   :inherit-environment: true
   :unset-environment: VAL1 VAL2
   :set-environment: VAL3="some value" VAL4="some other value"

TBH, I've not had a use case for this so my opinion is of limited value, but I think the conf.py setting would be the way to go.