Proposal: Mark up arg names in arg "about" text

[emlys]

In ARGS_SPEC "about" texts it is very common to refer to other args by name. For example, "A map of land cover for the future scenario. All values in this raster must have corresponding entries in the Carbon Pools table. Required if Calculate Sequestration is selected."

Objectives:

1. Reduce duplicated name text to minimize translation costs
2. Ensure consistent names. We don't always use consistent names to refer to args (e.g. "Do valuation" vs "Run economic analysis"). It's possible that when these are translated word-for-word, the meanings could diverge. It may not be clear in another language that they refer to the same thing. Even for our English-speaking audience, consistent names are clearer.
3. Be able to apply different formatting (capitalization patterns, bold) to the names within the "about" text

@phargogh suggested how to make a sort-of self-referential dictionary, which solves (1) and (2):

ARGS_SPEC = process({
    'arg1': {
        'name': 'Arg One',
        'about': 'asdfghhjk.'
    },
    'arg2': {
        'name': 'Arg Two',
        'about': 'This arg depends on {arg1}.'
    ...

def process(args_spec):
    for each arg:
        find any arg keys that are marked up with braces {} in the 'about' text
        look up those keys in args_spec
        and replace them with the corresponding 'name' value

Then, when we import the model, ARGS_SPEC['arg2']['about'] is 'This arg depends on Arg One.

Extending this to achieve (3), we could move the process() step outside of the model. Leaving in the marked-up keys, we could apply different formatting in the UG vs. the workbench. For example, if we wanted to make the names bolded, we could surround them with ** ** in the generated RST and <b> </b> in the HTML.

"about" texts have always been a human-readable plain text description (except a few places where we used HTML tags). They also haven't been used for anything, prior to the workbench and the Sphinx extension. So we're free to change the contract here.

[emlys]

@dcdenu4 @davemfish @phargogh this ties in to https://github.com/natcap/invest.users-guide/pull/34. Would love to get everyone's feedback!

[dcdenu4]

Hey @emlys , points 1 & 2 seem like a nice improvement to me. At first I had a slight concern of making it overly "complicated" to write args_spec with special syntax. However, I think this small special case makes it easier at the same time to maintain and write. I like it!

It's possible that when these are translated word-for-word, the meanings could diverge.

This is some great thoughtfulness. Consistency will matter when translating for sure.

[davemfish]

I think this is a good idea. Worth doing to end the inconsistent names problem.

And I think I like doing the process step outside of the model too because it's only for the benefit of a UI/docs layer.

[davemfish]

Another reason to have this process wrapper is to deal with serializing mentioned in #617