sphinx-doc / sphinx-doc/sphinx-argparse

Duplicate label warning

Open
#14 2 comments 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 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

  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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.