Consider auto-generating entire "data needs" and "interpreting results" sections

[emlys]

In the current implementation, our automated documentation works at the level of each individual model input. Each arg spec (and nested column, field, etc.) must have its own :investspec: in the RST source. This approach is flexible: we can mix the generated docs in with other text. But it requires more maintenance to keep the RST up to date with model API changes. We initially chose this tradeoff so that the generated docs would fit in seamlessly to existing documentation.

Now that we've lived with it for a while, I'm leaning towards reversing that tradeoff. We could modify the custom sphinx extension to generate docs at the level of an entire model. It would generate the whole "data needs" section (and "interpreting results", once natcap/invest#596 is done). Any text that's currently interspersed with the generated docs would have to go in a different section. We already use that format in some model chapters - for example in AWY there is an appendix that has more contextual information about the input data.

If we want the option to exclude certain args from the generated docs, that could be a new flag in the args spec, for example "document": False.