CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

1.24.2 (2026-11-04)

1.24.1 (2026-10-27)

Fixed

• Fix repository links in the PyPI project description (#376) by @gaborbernat.

1.24.0 (2026-10-10)

Added

• Require Python 3.11 and use Python 3.15 by default (#369) by @gaborbernat.

1.23.0 (2026-08-27)

Added

• Register CLI arguments as Sphinx program options so :option: can link to them (#346) by @gaborbernat.

Fixed

• Render positional arguments declared before add_subparsers() (#347) by @gaborbernat.
• Keep apostrophes in help text (#349) by @gaborbernat.
• Render argument groups without a title (#350) by @gaborbernat.
• Make :hook: intercept parse_intermixed_args() (#351) by @gaborbernat.
• Preserve raw formatter line breaks and render subcommand epilogs (#352) by @gaborbernat.
• Render option metavars, argument counts, and choices as in usage (#353) by @gaborbernat.
• Render list and multi-paragraph help under the option (#354) by @gaborbernat.
• Expand argparse format specifiers in help text (#355) by @gaborbernat.
• Strip ANSI colors from usage blocks (#356) by @gaborbernat.
• Skip subcommands whose help is suppressed (#357) by @gaborbernat.
• Expand {subcommand} to the subcommand name chain (#358) by @gaborbernat.

Documentation

• Name force_refs_lower correctly in the changelog (#348) by @gaborbernat.
• Explain that help text uses reStructuredText (#359) by @gaborbernat.

1.22.1 (2026-08-11)

1.22.0 (2026-07-20)

Added

• Add Python 3.15 support (#331) by @gaborbernat.

1.21.4 (2026-07-06)

Fixed

• Keep Sphinx smart quotes from rewriting --option names in descriptions, epilogs, and help text (#322) by @mmulqueen.

1.21.3 (2026-03-19)

Fixed

• Handle formatter subclasses and wrap preformatted blocks (#297) by @gaborbernat.

1.21.2 (2026-03-16)

Fixed

• Avoid a crash when a toctree title is empty (#296) by @gaborbernat.

1.21.1 (2026-03-02)

Documentation

• Restructure the README around common use cases (#292) by @gaborbernat.

1.21.0 (2026-03-02)

Fixed

• Render all tuple metavar elements and suppress None defaults (#287) by @gaborbernat.
• Propagate a :prog: override to subcommands (#288) by @gaborbernat.
• Handle multi-word program names in group titles (#289) by @gaborbernat.
• Remove a missing custom CSS reference (#290) by @gaborbernat.
• Use a section node when a toctree title is empty (#291) by @gaborbernat.

1.20.1 (2025-10-08)

Fixed

• Disable color codes while parsing a CLI (#252) by @gaborbernat.

1.20.0 (2025-10-08)

Added

• Add Python 3.14 support and end support for Python 3.10 (#251) by @gaborbernat.

1.19.0 (2024-12-10)

Added

• Handle nested subparsers (#207) by @ianw.

1.18.2 (2024-09-18)

1.18.1 (2024-09-08)

Documentation

• Fix the README by @gaborbernat.

1.18.0 (2024-09-08)

Added

• Add Python 3.13 support and end support for Python 3.9 (#184) by @gaborbernat.

1.17.0 (2024-08-06)

Added

• Add force_refs_lower for :ref: links with mixed-case program names and arguments (#179) by @ianw.

1.16.0 (2024-06-18)

Added

• Declare the extension safe for parallel reads by Sphinx (#171) by @JSCU-CNI.

1.15.0 (2024-04-17)

Added

• Support Sphinx 7.3 and end support for Python 3.8 (#163) by @gaborbernat.

1.14.0 (2024-03-22)

Added

• Allow content inside the directive (#158) by @mondeja.

1.13.1

Fixed

• Fix multiline handling of group descriptions (#152) by @mayrholu.

1.13.0

Added

• Add option to show usage before description (#148) by @mayrholu.

Fixed

• Don't render arguments with help=argparse.SUPPRESS (#149) by @mayrholu.
• Show epilogue if present in the command description (#146) by @mayrholu.

1.12.0

Added

• Support rendering with argparse.RawDescriptionHelpFormatter (#144) by @mayrholu.

1.11.1

Added

• Declare Python 3.12 support (#102) by @gaborbernat.

Fixed

• Fix broken end-user references (#95) by @webknjaz.

1.11.0

Added

• End support for Sphinx 6.1 by @gaborbernat.

1.10.0

Added

• Add the option to override the generated default part of the CLI parameter description (#56) by @berhoel.

1.9.0

Added

• Add the option to override the description using the description attribute of the directive (#45) by @Schamper.
• Add the option to retrieve the arguments by hooking argparse, in cases where func consumes the arguments and does not return them (#46) by @Schamper.

1.8.3

Fixed

• Fix project links after the move to tox-dev by @gaborbernat.

1.8.2

Fixed

• Don't raise label clashing warnings for options which only differ between upper and lower case (#34) by @mondeja.

1.8.1

Fixed

• Fix reference clashing for options which only differ between upper and lower case (#32) by @mondeja.
• Do not render default values for store_true and store_false actions (#30) by @mondeja.

1.8.0

Added

• Support Python 3.10 (#13) by @gaborbernat.

1.7.0

Added

• Support for adding custom subsection group title prefix (group_title_prefix and group_sub_title_prefix directive arguments) (#12) by @mondeja.

1.6.0 (2021-04-15)

Added

• Support for using the ref sphinx role to refer to all anchor-able objects generated by the tool by @gaborbernat.
• Flags now have their reference title set (for the HTML builder this is shown when hover over the reference) by @gaborbernat.
• Added a sphinx flag sphinx_argparse_cli_prefix_document (by default False) to avoid reference clashes when multiple documents generate the same reference labels by @gaborbernat.

Fixed

• Anchors generated no longer collapse multiple subsequent - characters (to avoid clash when there's a flag and a positional argument with the same name) by @gaborbernat.
• The root prog name now is prefixed for the root level optional/positional arguments' header (to avoid multiple anchors with the same id when multiple commands are documented in the same document) by @gaborbernat.

1.5.2

Changes

• Prefer a parser's description over its help message for subcommands by @gaborbernat.

1.5.1 (2021-04-15)

Documentation

• Update the README by @gaborbernat.

1.5.0 (2021-02-13)

Changes

• Display the metavar (fallback to dest) if the action has more than one argument (this is inline with how usage is displayed) by @gaborbernat.

1.4.0 (2021-02-13)

Changes

• Command line arguments are now bold to highlight them even further from the help text by @gaborbernat.

1.3.0 (2021-02-13)

Added

• Add support for changing the usage width via the usage_width option on the directive by @gaborbernat.

Changes

• Help messages are now interpreted as reStructuredText by @gaborbernat.

Fixed

• Mark document as always needs update (as the underlying content is coming from outside the sphinx documents) by @gaborbernat.
• Matching curly braces, single and double quotes in help text will be marked as string literals by @gaborbernat.
• Help messages containing the default(s) word do not show the default value (as often this indicates the default is already documented in the help text) by @gaborbernat.

1.2.0 (2021-02-05)

Added

• Add support for changing (removing) the title via the title attribute of the directive (#3) by @mondeja.

1.1.0 (2021-02-05)

Added

• Add support for setting the parser's prog with the directive's prog attribute (#1) by @mondeja.

1.0.0 (2021-02-05)

Added

• First version by @gaborbernat.