search

pyscaffold / configupdater

🌴 Parser like ConfigParser but for updating configuration files
https://configupdater.readthedocs.io/
Other
65 stars 9 forks source link

3.1: sphinx warnings #90

Closed kloczek closed 1 year ago

kloczek commented 2 years ago

Looks like lates sphinx shows some warning

+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.5.0
Creating file /home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/api/configupdater.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/api/modules.rst.
making output directory... done
[autosummary] generating autosummary for: api/configupdater.rst, api/modules.rst, authors.rst, changelog.rst, contributing.rst, index.rst, license.rst, usage.rst
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 8 added, 0 changed, 0 removed
reading sources... [100%] usage
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/option.py:docstring of configupdater.configupdater.Option.key:1: WARNING: duplicate object description of configupdater.configupdater.Option.key, other instance in api/configupdater, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/option.py:docstring of configupdater.configupdater.Option.updated:1: WARNING: duplicate object description of configupdater.configupdater.Option.updated, other instance in api/configupdater, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/option.py:docstring of configupdater.configupdater.Option.value:1: WARNING: duplicate object description of configupdater.configupdater.Option.value, other instance in api/configupdater, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/section.py:docstring of configupdater.configupdater.Section.name:1: WARNING: duplicate object description of configupdater.configupdater.Section.name, other instance in api/configupdater, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/section.py:docstring of configupdater.configupdater.Section.updated:1: WARNING: duplicate object description of configupdater.configupdater.Section.updated, other instance in api/configupdater, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/option.py:docstring of configupdater.option.Option.key:1: WARNING: duplicate object description of configupdater.option.Option.key, other instance in api/configupdater, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/option.py:docstring of configupdater.option.Option.updated:1: WARNING: duplicate object description of configupdater.option.Option.updated, other instance in api/configupdater, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/option.py:docstring of configupdater.option.Option.value:1: WARNING: duplicate object description of configupdater.option.Option.value, other instance in api/configupdater, use :noindex: for one of them
/usr/lib64/python3.8/configparser.py:docstring of configupdater.parser.MissingSectionHeaderError.filename:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/usr/lib64/python3.8/configparser.py:docstring of configupdater.parser.ParsingError.filename:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/section.py:docstring of configupdater.section.Section.name:1: WARNING: duplicate object description of configupdater.section.Section.name, other instance in api/configupdater, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/section.py:docstring of configupdater.section.Section.updated:1: WARNING: duplicate object description of configupdater.section.Section.updated, other instance in api/configupdater, use :noindex: for one of them
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-configupdater.3 { usage contributing license authors changelog api/modules api/configupdater } /home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/builder.py:docstring of configupdater.builder.BlockBuilder.section:: WARNING: more than one target found for cross-reference 'Section': configupdater.configupdater.Section, configupdater.section.Section
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/option.py:docstring of configupdater.option.Option:: WARNING: more than one target found for cross-reference 'Section': configupdater.configupdater.Section, configupdater.section.Section
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/option.py:docstring of configupdater.option.Option.section:: WARNING: more than one target found for cross-reference 'Section': configupdater.configupdater.Section, configupdater.section.Section
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/section.py:docstring of configupdater.section.Section.add_option:: WARNING: more than one target found for cross-reference 'Option': configupdater.configupdater.Option, configupdater.option.Option
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/section.py:docstring of configupdater.section.Section.get:: WARNING: more than one target found for cross-reference 'Option': configupdater.configupdater.Option, configupdater.option.Option
/home/tkloczko/rpmbuild/BUILD/configupdater-3.1/docs/../src/configupdater/section.py:docstring of configupdater.section.Section.get:: WARNING: more than one target found for cross-reference 'Option': configupdater.configupdater.Option, configupdater.option.Option
done
build succeeded, 18 warnings.
FlorianWilhelm commented 2 years ago

Thanks for posting this issue, @kloczek. It's really strange that we see this nested configupdater.configupdater causing the duplicate objects. Do you have any idea where this comes from by any chance?

kloczek commented 2 years ago

Sorry .. I've not been looking so deep 🤔

FlorianWilhelm commented 1 year ago

I started to look into this issue and it's actually way harder than I expected. Googling a bit it seems that the Napoleon Sphinx extension introduced this behaviour in newer releases. The reason seems to be that configupdater.configupdater imports some classes and makes them available via __all__. This leads, according to Sphinx, to an ambiguity as now several identical classes exists that can come from different modules. For me that makes no sense because even though you can import a class like Section from several modules, it's still the same class and thus I would always reference the module where it is defined.

From my understanding, in order to fix those warning, we would have to change the API. For instance I could get rid of one of the warnings by removing the import in configupdater.configupdater although this obviously leads to other problems. So we should not go down that road.

Another approach seems to be to add :noindex: to the generated api files. The problem with this solution is that currently we use sphinx-apidoc to generate those files on the fly, where we would have to add :noindex: to all classes, which cause an ambiguity. We could follow this approach by getting rid of apidoc and maintaining this manually (like it maybe is also supposed to be). I am not a huge fan of more manual work even though it will only happen rarely.

The third option is to learn to live with those warnings :-) My suggestion would be to follow this approach and rather one day switch over from sphinx to mkdocs, which is the more modern and much cleaner approach (in my opinion).

kloczek commented 1 year ago

You can peak on fixes that kind of issues in other projects https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/RDFLib/rdflib/pull/2036 https://github.com/click-contrib/sphinx-click/commit/abc31069 https://github.com/frostming/unearth/issues/14 https://github.com/jaraco/cssutils/issues/21 https://github.com/latchset/jwcrypto/pull/289 https://github.com/latchset/jwcrypto/pull/289 https://github.com/pypa/distlib/commit/98b9b89f https://github.com/pywbem/pywbem/pull/2895 https://github.com/sissaschool/elementpath/commit/bf869d9e

I've collected those links out of tickets which I've reported and already has been resolved 😋

FlorianWilhelm commented 1 year ago

Thanks @kloczek! This is really helpful.

FlorianWilhelm commented 1 year ago

Thanks a lot @abravalheri!