search

spatialaudio / nbsphinx

:ledger: Sphinx source parser for Jupyter notebooks
https://nbsphinx.readthedocs.io/
MIT License
441 stars 129 forks source link

Conflict between sphinx.ext.autosectionlabel and nbsphinx #787

Closed dkuegler closed 2 months ago

dkuegler commented 3 months ago

Hi,

I have activated nbsphinx and sphinx.ext.autosectionlabel in my sphinx documentation github.com/Deep-MI/FastSurfer and they run into a conflict.

Specifically, nbsphinx and autosectionlabel both try to create/embed ids for headings. But sphinxarg.ext already creates unique ids for each heading (but has duplicate heading names). Only the combination of the three then causes this bug / WARNING.

Please see this MWE.

~/sphinx-test$ make html
Running Sphinx v7.2.6
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [100%] script
/home/kueglerd/projects/sphinx-test/sphinx-test/script.rst:2: WARNING: duplicate label positional arguments, other instance in /home/kueglerd/projects/sphinx-test/sphinx-test/script.rst
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] script
generating indices... genindex done
copying linked files... 
copying notebooks ... 
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in _build/html.
mgeier commented 2 months ago

Thanks for the report and for the MWE which makes this easily reproducible!

Only the combination of the three then causes this bug / WARNING.

Are you sure you need all three to cause the problem? When I remove 'nbsphinx' from the extensions, I still get the warning.

It looks like there is already an issue at sphinx-argparse which doesn't involve nbsphinx: https://github.com/sphinx-doc/sphinx-argparse/issues/14

nbsphinx and autosectionlabel both try to create/embed ids for headings

nbsphinx indeed creates section IDs (because Jupyter uses a different scheme than Sphinx):

https://github.com/spatialaudio/nbsphinx/blob/311c53b57c2a8f1c84b358f307eb4a8121e14488/src/nbsphinx/__init__.py#L1275-L1299

However, this is only done for *.ipynb source files, and not for "normal" *.rst files:

https://github.com/spatialaudio/nbsphinx/blob/311c53b57c2a8f1c84b358f307eb4a8121e14488/src/nbsphinx/__init__.py#L534

So if I'm not mistaken, this isn't even active in your MWE.

It might lead to problems if a Jupyter notebook is involved, though?

dkuegler commented 2 months ago

I have done some further investigation and I know believe this is not an nbsphinx issue, but argparse. It was a bit hard to trace this issue, as it was thrown in auto section label and I subsequently searched for where labels where also created.