sphinx-doc / sphinx-doc/sphinx-argparse

Feature request: directive option to suppress the subcommands group heading without hiding subcommands

Open
#95 0 comments 0 reactions 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

Hello,

I'm a contributor of https://github.com/qgis-deployment/qgis-deployment-toolbelt-cli (aka QDT) and https://github.com/opengisch/qgis-plugin-ci/ where we are successfully using your project. Thanks for that, it's really useful and well designed.

We're facing an issue with sub-commands display with a duplicate header:

Image

When documenting a CLI that has subcommands, a common pattern is to document the root parser once (to show global options) and then document each subcommand individually via :path:. When the root parser uses add_subparsers(title="..."), sphinx-argparse renders that title as an h2 heading inside the root parser block even though the subcommands are already documented below it. This creates a duplicate or orphan heading with no useful content.

Steps to reproduce

Given a parser like):

subparsers = main_parser.add_subparsers(title="Sub-commands", dest="command")

And a documentation file using:

```{argparse}
  :module: my_wonderful_pypkg.cli
  :func: build_parser
  :prog: wonderful
  :noepilog:
```

The first directive renders a Sub-commands h2 heading listing the subcommands. The subcommands are then documented individually below. Result: a duplicate heading in the page structure.

Workarounds and drawbacks

  • :nosubcommands:: suppresses the subcommands list entirely, but also removes the heading. This is too coarse since the list is useful, only the heading is unwanted.

  • removing title= from add_subparsers() in the source code fixes the rendering, but alters the --help output of the CLI itself which is not what we want.

  • using :path: directives manually in the rst/md file but it requires more. It's what we're doing for now. And there is antoher issue: help is not displayed.

    • this block:
    ```{argparse}
      :module: qgis_deployment_toolbelt.cli
      :func: build_parser
      :path: deploy
      :prog: qdt
    ```
    
    • renders (note that the subcommand help is not displayed as description, in contrary with the first screenshot):
    Image

Proposed solution

Add a new directive option, for example :nosubcommandstitle: (or a more generic :nogroupheading:), that suppresses the heading generated for the subparser action group while keeping the list of subcommands intact.

Alternatively, a :nogrouptitles: option could suppress headings for all argument groups whose content would otherwise be empty or redundant, giving more control without requiring per-group options.

Environment

• sphinx-argparse 0.5.2
• Sphinx 9.1.0
• MyST-Parser (directive used as {argparse} in Markdown)

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 at the {argparse} directive handling for :nosubcommands: and the rendering of the add_subparsers(title="Sub-commands") action group. Add a directive option that suppresses only the group heading while retaining the subcommand list, then verify it with the reproduction configuration and confirm that :nosubcommands: behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.