sphinx-doc / sphinx-doc/sphinx-argparse
Duplicate label warning
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 38
- Forks
- 33
- PR merge metrics
- No merged PRs in 30d
Description
I am running Sphinx 4.4.0 with sphinx-argparse 0.3.1 and I am seeing the following warning when using subparsers:
/.../api/cli.rst:3: WARNING: duplicate label positional arguments, other instance in /.../api/cli.rst
/.../api/cli.rst:3: WARNING: duplicate label named arguments, other instance in /.../api/cli.rst
/.../api/cli.rst:3: WARNING: duplicate label positional arguments, other instance in /.../api/cli.rst
/.../api/cli.rst:3: WARNING: duplicate label named arguments, other instance in /.../api/cli.rst
In my conf.py, I have enabled sphinx.ext.autosectionlabel for extensions. Here is a MWE of my test case:
import argparse
from pathlib import Path
def clean() -> None:
pass
def run() -> None:
pass
def get_argparser() -> argparse.ArgumentParser:
cwd = Path.cwd().resolve()
out_dir = cwd / "build"
parent_parser = argparse.ArgumentParser(add_help=False)
parent_parser.add_argument(
"-v",
"--verbose",
action="store_true",
default=False,
help="Debug log level.",
)
parser = argparse.ArgumentParser(
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
subparsers = parser.add_subparsers(dest="subparser_name")
parser.add_argument(
"--version",
action="version",
version="1.0",
help="Display the version.",
)
# Clean workspace parser
parser_clean = subparsers.add_parser(
"clean",
help="Clean workspace and exit.",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
parser_clean.add_argument(
"path",
nargs="*",
default=out_dir,
type=Path,
help="Files and/or directories to permanently remove from the workspace.",
)
parser_clean.set_defaults(func=clean)
# Run subparser
parser_run = subparsers.add_parser(
"run",
parents=[parent_parser],
help="Run.",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
parser_run.add_argument(
"--no-backup",
action="store_true",
default=False,
help="Do not maintain timestamped artifacts.",
)
parser_run.set_defaults(func=run)
return parser
I am looking at the docs and it states it handles duplicated header names by appending a number X to the anchor name, but it doesn't appear this is working correctly. Either that or the anchor is ignored because I am using sphinx.ext.autosectionlabel?
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
Reproduce the warning with Sphinx 4.4.0, sphinx-argparse 0.3.1, the provided argparse example, and autosectionlabel enabled in conf.py. Inspect the generated labels for api/cli.rst and compare them with the linking-to-action-groups documentation. Done means the subparser documentation builds without duplicate-label warnings and its generated anchors remain usable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100