Feature request: ANSI color output in reference documentation

[serenity4]

Adding ANSI color support to @example blocks in #1441 was a great addition, and I'm wondering if we could have colorful reference documentation too?

Say I have a docstring with ANSI colors in them, it displays nicely in the REPL in help mode:

but as you might expect, through Documenter.jl the reference documentation spits out raw escape sequences:

Would it be reasonable to support ANSI colors in reference documentation? How much work would that require?

Thanks!

[goerz]

What does “a docstring with ANSI colors in them” look like in the source? Do you have an example project that uses them?

[serenity4]

Here is an example usage, though probably not the most readable. But it essentially does that:

StyledStrings seem to me like they would be a better fit for this, which I tried before resorting to ANSI colors. Currently the REPL help display doesn't support its color attributes:

While ideally I'd want both the REPL help and the Documenter reference to have colored output. @tecosaur are there plans to make Markdown.MD aware of StyledStrings styling during REPL display? If so, I'd be totally OK with supporting StyledStrings styling in reference docs instead of adding support for ANSI color. (though with #2488 we would get both as I understand it).

[goerz]

Interesting. This isn't exactly up to me, but to be honest, doing something like that doesn't seem like a good idea. Docstrings have to work in a lot of different contexts, and as a consequence (in my opinion) they should be relatively plain. If anything, I'd think you'd want some kind of semantic extension of the markdown syntax that then might be rendered in different colors in an appropriate context. But definitely not any kind of hard-coded colors. It makes the source much more difficult to read, not to speak of potential usability issues. Not everyone uses a dark-background terminal, even if that seems to be the current fashion for some reason. So "yellow" is often a problem. Personally, I would not add a feature to Documenter that would encourage something like that.

[serenity4]

In terms of usability issues, don't terminals use custom color mappings for ANSI codes? The color is not hardcoded, the ANSI code is, and IIUC which color is displayed on the screen is up to the terminal.

I completely agree on the fact that complicating docstrings with manually-input ANSI colors is generally not desirable, which is where StyledStrings support would be super helpful. Not only would docstrings be more readable, but they would also support the kind of extension that you mention since we'd have style attributes, which may be ignored for non-color outputs, instead of having ANSI escape sequences.

I brought up the idea of supporting ANSI colors in the display of Documenter reference documentation because that's the only way to get colors in docstrings at the moment AFAIK. Even though docstrings may indeed have to work in various contexts, I think allowing color is desirable, and is already possible; this feature request would only mean to support that in the documentation, because I don't see any harm in doing so. If StyledStrings were to be suitable and preferred for this, I'd be 100% aligned with that.

Regarding adding support for rendering ANSI colors, I don't think it would encourage people to write docstrings with ANSI colors anyways because 1. that's not very common to want extra colors in docstrings and 2. it requires extra work that most people just won't bother with. BUT, on some situations, colors may be helpful (in the example usage I provided, they are very useful to describe syntactic information), and if someone puts extra effort to get colors into a given docstring, it must have some value.

[tecosaur]

tecosaur are there plans to make Markdown.MD aware of StyledStrings styling during REPL display?

As of 1.12, it will be possible to use a styled language like so:

This allows for arbitrary styling, and can be interpreted outside the REPL by Documenter and friends. There's also syntax highlighting, but that's a slightly separate matter.

[serenity4]

Fantastic! I tried it out locally on nightly, and Documenter doesn't yet recognize this styling when rendering docstrings. That seems like the way to go, and I'd be willing to help with implementing support for it, if anyone would like to point me in the right direction. (though perhaps it's a bit early as 1.11 is not even released yet)