So the primary issue stems from the ID of the section being based on the section title:

https://github.com/ashb/sphinx-argparse/blob/bf1429aa0a4c51ae63d8d6baca0c163a5c6a3a64/sphinxarg/ext.py#L96

But those section titles are always the same:

https://github.com/ashb/sphinx-argparse/blob/bf1429aa0a4c51ae63d8d6baca0c163a5c6a3a64/sphinxarg/parser.py#L159-L168

So I see a couple solutions:

1. Allow the user to provide an id_prefix. Another option for something so small and low-level seems annoying. Could also be the user can specify the ID in its entirety.
2. Add some other information, for example from the parent node, to the ID in ext.py to make them depend on the uniqueness of something outside of sphinx-argparse.
3. Keep global state for sections and add a integer suffix (or other) to the IDs based on the number we've seen. Main problem with this is the complexity and that this extension is defined as allowing parallel reads. I can't imagine doing this correctly would be fun.

Ah option 2 wouldn't work if we're just using the parent node information as you could technically have two .. argparse:: directives in the same parent section.

I have a similar request: I would like to not have the headings Positional Arguments and Named Arguments at all (or have them not as headers). These headers give a messy TOC in the sidebar, e.g.:

One could have an option :noheaders:, e.g.:

.. argparse::
    :module: foo
    :func: _bar_parser
    :prog: bar
    :noheaders:

Yeah I thought I about adding something like that in my PR for fixing my need in #44. Or rather letting the user specify each header. Like :posheader: "" and :namedheader: "" would remove the section titles. Actually maybe they should be referred to as titles, not headers.

That said, your request brings up a harder question to answer. At least it makes me scratch my head. What does a section without a title look like? See this code in my PR for what I mean:

https://github.com/ashb/sphinx-argparse/pull/44/files#diff-c3ed14231074b274607bc7a6afc41f6a281fb8b575354e00b41fe667882be50fR96-R98

It's creating a section node then a title for that section. The docutils docs say that a section has a title: https://docutils.sourceforge.io/docs/ref/doctree.html#section. I'm not sure it is possible to have a section without a title. So then to make your request work you'd be talking about no sections at all...I suppose that might work. Might be some ugly if-statements, but could work.

Sorry, just brainstorming.