Difference to sphinx-doc/sphinx-argparse

[RobertoRoos]

Hi all, just something I was curious about. What is the difference between this package and the one over at https://github.com/sphinx-doc/sphinx-argparse / https://pypi.org/project/sphinx-argparse/ ?

Having two packages maintained for a very similar purpose seems like a bit of a waste. Is it an option to combine both repositories?

[RobertoRoos]

Hi folks, I was remembering this suddenly. Any thoughts on this matter in the end?
@gaborbernat maybe?

[gaborbernat]

Why sphinx-argparse-cli was created:

When I created it in February 2021, sphinx-argparse was effectively dormant — the original repo (alex-rudakov/sphinx-argparse) had its last release in 2018, and the revival under ashb was still early. The move to sphinx-doc and the modernized 0.5.x releases didn't happen until mid-2024, over 3 years later.

Key differences in design:

	sphinx-argparse	sphinx-argparse-cli
Approach	Intermediate dict structure, then rendered to nodes	Direct docutils node construction (no intermediate format)
Subcommands	Supported, navigated via :path:	Core design goal — "sub-commands friendly", recursive by default
Cross-referencing	Domain-based linking added recently (v0.6.0-dev)	Built-in from early on — every flag/subcommand gets a :ref: anchor
Hook mode	N/A	Can intercept parsers that aren't returned (monkey-patches parse_known_args)
Content customization	@before/@after/@replace/@skip classifiers	Template variables for titles, pass-through RST content
Markdown in help	Yes (:markdownhelp:)	No (RST only, but RST in help strings is parsed)
Man page support	Yes (:manpage:)	No

Merging?

The two have diverged significantly in architecture and API surface. sphinx-argparse generates an intermediate dict then renders it; sphinx-argparse-cli builds the docutils node tree directly. They have different directive names, different option sets, and different extension points. A merge would effectively mean rewriting one to match the other, breaking existing users either way.

Both serve their users well — sphinx-argparse has broader adoption (~84x more downloads) due to its longevity and sphinx-doc backing, while sphinx-argparse-cli is used by projects like tox and pypa-build that need deep subcommand support with cross-referencing out of the box.

[RobertoRoos]

Wow, thanks for the very clear answer, cool.

So the differences are quite fundamental. It's a bit of shame because it feels like double effort to maintain both packages. Another consideration is that sphinx-doc/sphinx-argparse isn't particularly healthy has a project. Comparing the regularity of commits of both packages over the last 2 years:

Have you considered moving under the sphinx-doc/ namespace too?

[gaborbernat]

Not sure I see the benefits of doing so 🤔

[RobertoRoos]

It gives a kind of authority to an extension, I think. If it's hosted under the Sphinx organization it shows it must be legit.
Well, it's not important now.

[gaborbernat]

The downside of doing that is that suddenly there are a lot of maintainer-level issues, such as permissioning and stuff, that inevitably we would run into. And technically this project is maintained by this organization, not that one, so having it here feels more correct.