sphinx-doc / sphinx-doc/sphinx-argparse

How to parse inline code both on command line and rst?

Open
#68 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
38
Forks
33
PR merge metrics
No merged PRs in 30d

Description

I have some arguments with inline code. For example:

    group_exec.add_argument(
        "--dry-run",
        "--dryrun",
        "-n",
        dest="dryrun",
        action="store_true",
        help="Do not execute anything, and display what would be done. If you have a very large workflow, use `--dry-run --quiet` to just print a summary of the DAG of jobs.",
    )
Ideally, this would show as:

Do not execute anything, and display what would be done. If you have a very large workflow, use --dry-run --quiet to just print a summary of the DAG of jobs.

But, since it gets converted to RST, it gets parsed as:

Do not execute anything, and display what would be done. If you have a very large workflow, use `--dry-run --quiet` to just print a summary of the DAG of jobs.

I guess I could have:
    group_exec.add_argument(
        "--dry-run",
        "--dryrun",
        "-n",
        dest="dryrun",
        action="store_true",
        help="Do not execute anything, and display what would be done. If you have a very large workflow, use ``--dry-run --quiet`` to just print a summary of the DAG of jobs.",
    )

But it would look weird when running -h in the command line.

Is there a way to show the help in the command-line as single back-ticks but to be rendered as inline code?

thanks,

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing how argparse help text is converted to RST and how the same text is displayed by the command-line -h output. Check whether inline-code markers can be interpreted differently in these two paths without changing ordinary help text. Done means single backticks render as inline code in RST while command-line help remains readable.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.