1.0.0: sphinx warnings `reference target not found`

[kloczek]

On building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues. Here is the output with warnings:

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
loading translations [en]... done
making output directory... done
loading intersphinx inventory from https://docs.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] installing
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/demo.rst:261: WARNING: Footnote [4] is not referenced.
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/demo.rst:267: WARNING: Footnote [11] is not referenced.
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/demo.rst:18: ERROR: Undefined substitution referenced: "problematic".
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/demo.rst:261: ERROR: Unknown target name: "5".
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/demo.rst:304: ERROR: Unknown target name: "body elements".
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/demo.rst:316: ERROR: Unknown target name: "hyperlink reference without a target".
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/development.rst:100: WARNING: duplicate label release-1.0.0, other instance in /home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/changelog.rst
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx_rtd_theme.3 { installing configuring development contributing changelog demo/structure demo/demo demo/lists_tables demo/api demo/long } /home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/installing.rst:42: WARNING: undefined label: 3.0.0
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:51: WARNING: 'class' reference target not found: boolean
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:58: WARNING: 'class' reference target not found: boolean
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:66: WARNING: 'class' reference target not found: integer
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:75: WARNING: 'class' reference target not found: boolean
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:83: WARNING: 'class' reference target not found: boolean
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:105: WARNING: 'class' reference target not found: string
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:112: WARNING: 'class' reference target not found: boolean
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:128: WARNING: 'class' reference target not found: URL
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:135: WARNING: 'class' reference target not found: boolean
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:143: WARNING: 'class' reference target not found: boolean
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:151: WARNING: 'class' reference target not found: string
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:158: WARNING: 'class' reference target not found: boolean
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:168: WARNING: 'class' reference target not found: string
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/configuring.rst:177: WARNING: 'class' reference target not found: string
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/development.rst:44: WARNING: undefined label: 2.0.0
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/development.rst:104: WARNING: undefined label: 0.5.2
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/development.rst:123: WARNING: undefined label: 3.0.0
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/development.rst:126: WARNING: undefined label: 2.0.0
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/development.rst:136: WARNING: undefined label: 1.0.0
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/contributing.rst:5: WARNING: unknown document: rtd:code-of-conduct
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/contributing.rst:151: WARNING: unknown document: rtd:development/i18n
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/demo.rst:275: WARNING: citation not found: nonexistent
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/api.rst:7: WARNING: py:mod reference target not found: test_py_module
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/api.rst:7: WARNING: py:mod reference target not found: test_py_module
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/test_py_module/test.py:docstring of test_py_module.test.Foo.__init__:: WARNING: py:class reference target not found: string
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/test_py_module/test.py:docstring of test_py_module.test.Foo.capitalize:: WARNING: py:class reference target not found: string
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/test_py_module/test.py:docstring of test_py_module.test.Foo.capitalize:: WARNING: py:class reference target not found: string
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/api.rst:34: WARNING: cpp:identifier reference target not found: Sphinx
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/api.rst:61: WARNING: cpp:identifier reference target not found: MySpecificEnum
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/api.rst:86: WARNING: js:class reference target not found: ModTopLevel
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/lists_tables.rst:: WARNING: "table cell spanning" not supported
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/lists_tables.rst:: WARNING: "table row spanning" not supported
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/lists_tables.rst:: WARNING: "table row spanning" not supported
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/lists_tables.rst:: WARNING: "table cell spanning" not supported
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/lists_tables.rst:: WARNING: "table cell spanning" not supported
/home/tkloczko/rpmbuild/BUILD/sphinx_rtd_theme-1.0.0/docs/demo/lists_tables.rst:: WARNING: "table cell spanning" not supported
done
build succeeded, 44 warnings.

[stsewd]

Hi, most of those (maybe all) from the demo/*.rst files are on purpose to test how they look like with the theme.

[benjaoming]

Closing this :+1:

@kloczek I hope this can work for you as a RPM package maintainer -- but the theme is deliberately doing some stuff in the demo to test even how unrecommended documentation structures will look like.

[kloczek]

This issue is not about me and what I'm doing 😄 I'm interested only roff output (man page) and broken refs are not affection roff output. Mostly this issue affested html and and few other output formats (IIRC sphinx can render ~15 formats). I've reported that only because I see those warnings during my build I've been thinking that it is good to provide such feedback about what I've spotted 😋

[tkloczko@pers-jacek SPECS]$ grep ^%sphinx_build_man python-*spec | wc -l; ls -1 python-*spec|wc -l
516
1080

As you see almost half of my packages with python modules have documentation includes as man pages (still it is common and most obviouse documentation format in U*ix world 😋 )

[benjaoming]

@kloczek as we've pointed out these warnings are anticipated because the demo included in the documentation is intended to demo how broken things look.

A lot of the warnings originate from this particular section: https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#references

If this is causing actual issues for you, please say so. If you can live with the warnings, that's great -- I also find them a bit annoying, but I don't have a good solution to getting rid of them :)

[kloczek]

Will add note in my spec file to not forget that it is intentional. Thank you 👍