4.1.0: sphinx 4.0.3 warnings

[kloczek]

[tkloczko@barrel scons-4.1.0]$ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.0.3
making output directory... done
WARNING: html_static_path entry '_static' does not exist
[autosummary] generating autosummary for: SCons.Node.rst, SCons.Platform.rst, SCons.Scanner.rst, SCons.Script.rst, SCons.Tool.rst, SCons.Variables.rst, SCons.compat.rst, SCons.rst, index.rst
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to determine Null(0x7FD5E2203EE0) to be documented, the following exception was raised:
Handler <function _skip_member at 0x7fd5e253f820> for event 'autodoc-skip-member' threw an exception (exception: cannot unpack non-iterable Null object)
WARNING: autodoc: failed to determine Null(0x7FD5E2203EE0) to be documented, the following exception was raised:
Handler <function _skip_member at 0x7fd5e253f820> for event 'autodoc-skip-member' threw an exception (exception: cannot unpack non-iterable Null object)
WARNING: autodoc: failed to determine Null(0x7FD5E2203EE0) to be documented, the following exception was raised:
Handler <function _skip_member at 0x7fd5e253f820> for event 'autodoc-skip-member' threw an exception (exception: cannot unpack non-iterable Null object)
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/dblite.py:docstring of posix.chown:16: WARNING: Unexpected indentation.
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/dblite.py:docstring of posix.chown:17: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Conftest.py:docstring of SCons.Conftest:60: WARNING: Unknown target name: "have".
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Node/__init__.py:docstring of SCons.Node.Node.Attrs:1: WARNING: duplicate object description of SCons.Node.Node.Attrs, other instance in SCons.Node, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Node/__init__.py:docstring of SCons.Node.Node.Attrs:1: WARNING: duplicate object description of SCons.Node.Node.Attrs, other instance in SCons.Node, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Node/__init__.py:docstring of SCons.Node.Node.Attrs:1: WARNING: duplicate object description of SCons.Node.Node.Attrs, other instance in SCons.Node, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Node/__init__.py:docstring of SCons.Node.Node.Attrs:1: WARNING: duplicate object description of SCons.Node.Node.Attrs, other instance in SCons.Node, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Node/__init__.py:docstring of SCons.Node.Node.Attrs:1: WARNING: duplicate object description of SCons.Node.Node.Attrs, other instance in SCons.Node, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Node/__init__.py:docstring of SCons.Node.Node.Attrs:1: WARNING: duplicate object description of SCons.Node.Node.Attrs, other instance in SCons.Node, use :noindex: for one of them
WARNING: autodoc: failed to determine Null(0x7FD5E2203EE0) to be documented, the following exception was raised:
Handler <function _skip_member at 0x7fd5e253f820> for event 'autodoc-skip-member' threw an exception (exception: cannot unpack non-iterable Null object)
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Script/SConsOptions.py:docstring of optparse.OptionParser.parse_args:3: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/tkloczko/rpmbuild/BUILD/scons-4.1.0/SCons/Variables/PathVariable.py:docstring of SCons.Variables.PathVariable:12: WARNING: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... sconsapidocs.1 { SCons SCons.Node SCons.Platform SCons.Scanner SCons.Script SCons.Tool SCons.Variables SCons.compat } done
build succeeded, 16 warnings.

The manual pages are in build/sphinx/man.

BTW .. do you have any plans to make new release?

[mwichmann]

indeed... this one is a particular favorite of mine:

WARNING: autodoc: failed to determine Null(0x7FD5E2203EE0) to be documented, the following exception was raised:
Handler <function _skip_member at 0x7fd5e253f820> for event 'autodoc-skip-member' threw an exception (exception: cannot unpack non-iterable Null object)

this funky object is used as a sentinel but expects to be able to be accessed without throwing an error, presumably to avoid a type check. Various code checkers don't like it, either.

A new release is in the works, for a hint of what will be in it: https://github.com/SCons/scons/milestone/30

[bdbaddog]

Which version of sphinx are you using?
From our requirements.txt

# Packages needed for development, packaging, and distribution, but not for running SCons

# This will check if the README.rst will render o.k. on pypi and not block an upload
# Can be used with twinecheck
# See: https://github.com/pypa/readme_renderer
readme-renderer
# 3.5.0 is bad. Hold at 3.4.3 for now until 3.5.1 is available
sphinx<3.5.0
sphinx_rtd_theme
lxml==4.6.3
rst2pdf
ninja

[kloczek]

Which version of sphinx are you using?

on top of the output is:

Running Sphinx v4.0.3

and the ame is in tiket title😜

Sphinx 4.x usually is more sensitive to some issues so solving those warning probably should not affect cases when 3.x is used.

[bdbaddog]

Hmm. Is this worth leaving open. For now we're sticking with earlier sphinx.
(@mwichmann thoughts?)

[kloczek]

BTW as sphinx 4.x is usually more sensitive to some issue usually fixing that version if sphinx warnings do not affest use older 3.x😜

[mwichmann]

The state of the sphinx build is that some of the gripes from the 4.1.0 source are fixed in git, and some aren't - sometimes because I'm not sure how to proceed (the Null class) and sometimes because it's not actually our error (in one case it follows up the chain to the Python stdlib file which has a non-Sphinx-compliant docstring). I think I've built with 4.0, but the "native" sphinx-build here (Fedora 34) is still 3.4.3 so that's what I usually get. Some of the gripes were new. I don't see any reason not to leave this sticking around as a reminder.

[mwichmann]

As an FYI, it is now possible to "build" SCons without doing the Sphinx build, if such is valuable from a distro packaging perspective. Example

python3 scripts/scons.py SKIP_DOC=pdf,api

That skips both the apidocs (Sphinx) step, and the fop convert-to-pdf step, leaving you with just the manpages built as .1 files and html output.

It also works to do the manpage builds separately, and omit pdf generation there:

cd doc/man && python3 ../../scripts/scons.py SKIP_PDF=1