sphinx-doc / sphinx-doc/sphinx-argparse
Feature request: directive option to suppress the subcommands group heading without hiding subcommands
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:
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=fromadd_subparsers()in the source code fixes the rendering, but alters the--helpoutput 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
helpis not displayed as description, in contrary with the first screenshot):
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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