Workbench: Structured text in plugin "about" text

[phawthorne]

Background/Motivation

I'm developing plugins and want to be able to provide structured text in the "about" boxes (i.e. the info tooltips in the workbench interface).

Description

It would be really helpful to be able to have structured text in the about boxes. Some things I want to be able to do:

• Include paragraph breaks to separate a quick introductory sentence from a more detailed description
• Apply formatting to keywords (e.g. bold or italics)
• Create formatted lists. In my current use case in the ROOT plugin specifically, there is a dropdown with some choices about the algorithm and I want the helper text to have a list with one entry per choice.

In the old version of ROOT that was built with the Qt interface engine, I could use html to provide formatting e.g. break tags for line breaks or ul/li tags for lists. That could work, but if possible, I'd prefer switching to markdown.

Benefits

This addition would give plugin authors the ability to provide more helpful "about" text than they are currently able to do, which would provide users better inline documentation and make use of the tools more streamlined. Markdown would be easy for developers to use.

Mitigation of side effects

I don't think there would be any side effects with Markdown. Using html might require some sanitization.

Alternatives

The only alternative now is to do the best we can in the about text and refer users to external documentation.

Additional context

NA

[emlys]

Thanks for the request @phawthorne!

why it is like this now

It was a design decision to remove formatting from the "about" text (some of which formerly contained HTML tags from the days of the Qt app). The reason being that there are now multiple consumers of that text, and they don't necessarily understand the same markup language. The "about" attribute is used by the workbench, the user guide, the compute API currently in development, and any potential clients of the invest python API. Plain text is the only option that's usable by all of them. Returning text containing HTML tags in the JSON response from the compute server would be undesirable, for instance.

For core invest models, the "about" text is brief, like 1 sentence. Any description beyond that goes in the user guide RST document. I think this is a reasonable balance:

• UI design principles dictate that tooltips should be concise, meant for a quick glance. A paragraph-long tooltip can get in the way of other page elements, has limited formatting possibilities, and becomes difficult to read when there is a lot of tiny text. I would hazard a guess that it's problematic for accessibility tools, too.
• Keeping more complex descriptions in a separate document gives us the freedom to use virtually unlimited formatting options, and gives the user more freedom in how to interact with the document.

I'm interested to hear if you agree, or do you have a use case where this reasoning doesn't make sense?

how can we better support plugin documentation?

We haven't really tried to address the question of how plugins should provide a user guide or other documentation. In core invest models, the tooltip includes a link to the corresponding header in the user guide page. Would it address your use case if we supported linking from a plugin tooltip to a separate documentation page, like we do for core models?

I'm not a fan of ReStructuredText, I'd probably go with Github Markdown if that's sufficient. But I am imagining the plugin developer would write their formatted documentation in a separate page, and we would automatically link from the input to the corresponding section of docs by using the ID.

[davemfish]

One thing we could do, while respecting the need to stick with plain text, is render the about text from each nested input in the info modal. For example, @phawthorne mentioned a dropdown input, and I took the liberty of finding it in your plugin:

spec.OptionStringInput(
            id="frontier_type",
            name="Analysis Type",
            options=[
                spec.Option(key="weight_table"),
                spec.Option(key="frontier"), 
                spec.Option(key="n_dim_frontier"),
                spec.Option(key="n_dim_outline")
            ],
            about="Determines the mode of operation for the optimizer. "
                "Can be: <ul><li>weight_table: use to provide "
                "particular objective weights for a given number of "
                "optimization runs.  </li><li>frontier: evenly-spaced "
                "frontier (requires exactly two objectives in "
                "objectives table).</li> <li>n_dim_frontier: use for "
                "more than two objective analysis.  Randomly samples "
                "points on N dimensional "
                "frontier.</li><li>n_dim_outline: constructs 2D "
                "frontiers for all pairs of objectives.</li></ul>",
            required="do_optimization"
        ),

Each Option can actually have an about attribute. That attribute is already supported, just not displayed in the Workbench. So, in the Workbench, we could have the info modal for Analysis Type render a nicely formatted list that includes the names and descriptions for each Option. That seems like it would be a nice enhancement for plugins and a number of core invest models. It would also work for CSV Inputs with required columns and their descriptions.

Do you think that would meet your needs, @phawthorne ?

[phawthorne]

Thanks @emlys! I appreciate that it was a deliberate choice for the InVEST tools and can see that logic.

I think there may be additional context now that the about text will be used by plugin authors who don't need to interface with any of those other tools and may have different preferences about how to develop/provide documentation. Personally, I would love to be able to have my documentation include a list or to add some formatting to help make the information as clear as possible to the user. In ROOT, I do have a link to the full on GitHub pages-hosted RST documentation that shows up in the workbench through the pyproject file, and I like your idea to make a page with links in to specific sections for each form element, but the tooltip will be users' most convenient place to check for clarifications.

Some additional thoughts:

• The about text popups already take over the whole screen with a modal box rather than operating like mouse-over tooltips, so I don't think their size is a major issue in the context of the workbench. Given this behavior, I've been thinking about the about text as more of a docstring/mini users guide section than a single sentence tooltip.
• I think maximally helpful information as close as possible to its point of application is the documentation that helps people the most, and things like lists, paragraph breaks, and formatting can go a long way to making even short text more useful. It's obviously not going to make or break plugins to have formatting in the about text, but I still think it would be a nice quality of life offering to developers and users.
• Markdown for sure.
• I would argue that giving developers more tools and flexibility is going to be a good thing for plugins generally, and InVEST-specific constraints can be applied to InVEST models.

I also have to admit I have no idea how hard this would be, so if benefit/cost just doesn't make sense, I totally understand striking this from consideration.