Section numbers wrong when multiple argparse directives used in single page

[djhoese]

This is a rewrite of https://github.com/alex-rudakov/sphinx-argparse/issues/127 from the old project, but I've made it into a smaller reproducible example. The summary of the issue is that Named Arguments and Options sections in a single restructuredtext document (~or maybe a single sphinx project~) that has a :numbered: TOC tree will always use the section number from the last .. argparse:: directive.

mkdir sample_proj
cd sample_proj
touch myproj.py
touch index.rst
touch utils.rst

myproj.py

def get_parser1(parser):
    parser.add_argument("--flag1", default=1, type=int)
    return parser

def get_parser2(parser):
    parser.add_argument("--flag2", default=2, type=int)
    return parser

index.rst

Welcome to myproj's documentation!
==================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   :numbered:

   utils

utils.rst

Utility Scripts
===============

Section A
---------

.. argparse::
    :module: myproj
    :func: get_parser1
    :passparser:

Section B
---------

.. argparse::
    :module: myproj
    :func: get_parser2
    :passparser:

Then generate the docs with:

PYTHONPATH=. sphinx-build . build -C -D extensions=sphinxarg.ext

And open built/utils.html in a browser. You'll see something like:

Notice how the "Named Arguments" sections have the same section number. They should be 1.1.1 and 1.2.1.

[djhoese]

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.

[djhoese]

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.

[tdegeus]

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:

[djhoese]

Yeah I thought I about adding something like that in my PR for fixing my need in https://github.com/ashb/sphinx-argparse/pull/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.