Docstring hyperlink

[Gracecr]

I'd like to include a hyperlink in my long_description. If I include a link, my TE allows me to CTRL+click it, which is great, but I'd rather not have the full link print if I can avoid it. I see that some TEs have support for hyperlinks, and it seems like rich supports this (bottom of section). Is there a way I can achieve this with cyclopts?

My hunch is "not currently" as I see that long_description is added as a single Text component with the style "info". It'd be cool if it could be parsed as markdown, but I understand why that'd be a bad default.

Also, really nice library. I've used click in the past. I was going to try typer, but I saw this project mentioned in an issue about Unions. Very impressed.

[BrianPugh]

So I'm strongly considering adding some sort of formatting support for docstrings. Markdown would be one of those options, but RST is also a natural choice. Unfortunately, rich doesn't have native rst support. I think it would manifest itself in a way like:

app = App(docstring_format="markdown")

[BrianPugh]

@Gracecr would you mind playing around with #85 and see what you think? Currently only "text" (default behavior) and "markdown" are implemented. We can add RST later if we figure out a maintainable solution.

[Gracecr]

Markdown looks gorgeous! Seems like most everything is working in the VSCode integrated terminal. Even code blocks with syntax highlighting and tables are working!

I'm not seeing any new bugs introduced with this PR.

[BrianPugh]

do you think the API is fine? i.e. the field name being help_format, the two valid explicit options being "text" and "markdown", and it's documentation being:

       The markup language of docstring function descriptions.
       If ``None``, fallback to parenting :attr:`~.App.help_format`.
       If no :attr:`~.App.help_format` is defined, falls back to ``"text"``.

[Gracecr]

Seems like a reasonable API to me. I would try to make it prominent in the docs. It's too nice of a feature for users to not know about it!

[BrianPugh]

follow up question: do we think "markdown" or "text" is a more reasonable default? The markdown looks much nicer.

[Gracecr]

follow up question: do we think "markdown" or "text" is a more reasonable default? The markdown looks much nicer.

Good question. I agree that it likely improves the look of the average user's output. On the other hand, it is non-standard in the python world.

I think markdown default still gets my vote. If a user doesn't intend to use it, it probably won't change their output. If it does, it probably looks better. On the off chance it messes up their formatting, they can always switch to "text".

[BrianPugh]

I'll investigate if I can reasonably add rst support. RST would be a good, python-sane default. If I cannot, I agree that I think setting "markdown" as the default is reasonable.

[BrianPugh]

Alright so, here's my thought process:

1. rich-rst appears to be what we want, but it only has 9 stars on github.

2. rich-rst stems from this discussion in the rich repo.

3. rich-rst itself doesn't have any subdependencies, which is good. The module itself is only like 700 lines of code in an __init__.py.

4. willmcgugan, creator of rich, uses rich-rst as a dependency in rich-cli, which has nearly 3k stars at the time of this writing.. That said, he hasn't really touched that project in 2 years.

So, I think I'll do the following:

1. Add rich-rst as a dependency.
2. Add the following help_format: "restructuredtext", "rst" (alias for restructuredtext) and "md" (alias for markdown).
3. Rename "text" option to "plaintext" for additional explicitness.
4. Make the default help_format option be "rst".
5. Update documentation, maybe make a whole page for this.

@Gracecr what do you think of this plan?

[Gracecr]

Sounds like a solid plan! Looks like RST also won't mess with plaintext, so users who don't intend to use any special formatting shouldn't even notice that their help text is being rendered as RST. The aliases are also a good idea.

I'm more of a markdown guy myself, but I can take a look if any issues pop up with rich-rst.

[BrianPugh]

this is now in v2.2.0, thanks!