Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Help text indentation renders differently in rendered docs vs. --help output #1720

Open
Tracked by #1642
victorlin opened this issue Jan 14, 2025 · 1 comment
Open
Tracked by #1642
Labels
documentation Improvements or additions to documentation

Comments

@victorlin
Copy link
Member

Consider this example from #1709 (comment):

        help=f"""Custom date formats for values in the provided date fields, defined by standard
                 format codes available at
                 <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes>.
                 If a value matches multiple formats, it will be parsed using the first match.
                 The following formats are builtin and automatically used:
                 {", ".join(repr(x).replace("%", "%%") for x in BUILTIN_DATE_FORMATS)}.
                 User-provided values are considered after the builtin formats.""")

It renders badly in Sphinx:

Screenshot 2025-01-13 at 7 52 00 PM

This can be fixed by applying dedent (49568ad).

The indentation is ignored in --help output which strips all newlines and indentation, but this behavior has its own downsides.

Possible solutions

  1. Use dedent for all multi-line help strings.
  2. Update the source code → rST converter to ignore indentation while keeping newlines.
@victorlin victorlin added the documentation Improvements or additions to documentation label Jan 14, 2025
@victorlin victorlin changed the title Help text indentation renders differently in --help output vs. rendered docs Help text indentation renders differently in rendered docs vs. --help output Jan 14, 2025
@joverlee521
Copy link
Contributor

I see nextstrain/cli uses a combination of dedent and cleandoc (GH search). Seems like cleandoc is cleaner in that you don't need to end the first line with \.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants