Formats Per-Command Help Output

[HassanAbouelela]

Closes #1232

Description

Modifies the docstring sent for per-command help to remove weird formatting issues mentioned in #1232. Removes newlines that are not used for paragraph breaks, after retrieving the docstring, and lets the embed handle it on the discord side.

The Old and Updated Output for Reference

[ghost]

Thank you for contributing to Python Discord!

Please check out the following documents:

• Join the Discord server! - If you have not already, join the Discord server and introduce yourself in our #dev-contrib channel.
• Python Discord Contributor Wiki - A set of resources about setting up our services
• Python Discord Code of Conduct - Code of conduct for our community
• CONTRIBUTING.md - Guidelines on contributing to this repository

[Numerlor]

This breaks the help of multiple commands like tempban or doc.
Is this worth taking care of? I don't think there's a proper way for us to differentiate between newlines added for readability in the source and the ones that are also necessary in the help output. That'd mean we'd have to change the docstrings with some special syntax or using line continuation which imo is not worth the tradeoff of complicating how it looks in the source code for the small improvement to what's sent on discord

[HassanAbouelela]

I tested this with all the commands I could find in help, and I got the following:

Broken:

• tempban
• tempmute
• tempvoiceban
• superstarify

Improved:

• eval
• close

I'm not actually seeing any difference in doc, so I won't address it. All the other broken commands have their doc syntax in common. I'm seeing a few possible solutions:

1. Modify the doc of eval and close.
2. Modify the docs of the broken commands.
3. Add a check for the doc syntax of the broken commands. (I've prepared an implementation for this if this approach is of interest.)
4. Ignore and close the issue.

[Numerlor]

I'm not actually seeing any difference in doc, so I won't address it. All the other broken commands have their doc syntax in common. I'm seeing a few possible solutions:

1. Modify the doc of eval and close.
2. Modify the docs of the broken commands.
3. Add a check for the doc syntax of the broken commands. (I've prepared an implementation for this if this approach is of interest.)
4. Ignore and close the issue.

Sorry, it's the get subcommand of doc. Doing the checks at runtime doesn't sound like it's worth it to me, as new commands that may use the newlines in a way that shouldn't be stripped most probably won't be affected by it.
If only the two commands you mentioned get an improvement the manual solution wouldn't be that bad as the amount of affected commands and thus their docstring is that small

[HassanAbouelela]

Superstarify needs to be fixed too.

[HassanAbouelela]

As a bit of an update, there is no real good way to fix the output, without changing the docstrings. Paragraphs that pass the 80 character limit have to be spaced onto multiple lines for linting, but discord embeds can't really automatically handle that. There is no good way to stay under the limit, and present a good output.

This means we will have to shorten or break up the broken doc strings or implement a parsing solution.

[ChrisLovering]

Do we just go for the easy, but tedious, solution and update the doc strings? I think the other options are complex and would add maintenance burden.

We could then just ensure we test what the help embed looks like for future commands before approving.

[Xithrius]

Do we just go for the easy, but tedious, solution and update the doc strings?

@ChrisLovering this is probably the best way to do it for now.

[Xithrius]

@HassanAbouelela we should probably open up another PR to fix the necessary docstrings.

[HassanAbouelela]

Just to clarify, which solution is this?

There are two similar solutions. The first one is the change added by this PR + changing the doc strings of time units.

The other is to change every single docstring that takes more than one line.

[Xithrius]

I think we're going for the 1st option. @ChrisLovering, opinions?

[ChrisLovering]

Yea, the former. We should have a mechanism to force a line break when needed though, for when we need to do things like the time units in future.

[HassanAbouelela]

I had actually written a small patch to allow for forcefully breaking lines (more specifically, I used the escape sequence used for time units -- \u2003 -- as a non-escapable break).

The implementation had the added benefit of not requiring any docstring changes. At this point, it's gone, and this PR is very outaded, but it should be pretty easy to take the work already done here, add on the patch I just described in a new PR.

[Xithrius]

@HassanAbouelela I think we should make a new PR for the docstrings if we are to manually format them.

[ChrisLovering]

This has been taken over by #1876