Docstring hyperlink about cyclopts HOT 11 CLOSED

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.

from cyclopts.

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.

from cyclopts.

this is now in v2.2.0, thanks!

from cyclopts.

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")

from cyclopts.

@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.

from cyclopts.

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.

from cyclopts.

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"``.

from cyclopts.

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!

from cyclopts.

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

from cyclopts.

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".

from cyclopts.

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?

from cyclopts.