unknown node type ifconfig in sphinx 5.0.0

[djhoese]

Describe the bug

My project's CI just switched to sphinx 5.0.0 and I'm unable to generate my documentation that depends heavily on ifconfig. In this particular case there seems to be an issue with doing an .. include:: of a file that uses ifconfig.

source/overview.rst:46: WARNING: unknown node type: <ifconfig: <comment...><paragraph...><paragraph...><paragraph...>>

Exception occurred:
  File "/home/davidh/miniconda3/envs/polar2grid_py310/lib/python3.10/site-packages/docutils/nodes.py", line 2068, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.html5.HTML5Translator'> departing unknown node type: ifconfig

How to Reproduce

$ git clone https://github.com/ssec/polar2grid
$ conda env create -n polar2grid -f continuous_integration/environment.yaml
$ conda activate polar2grid
$ cd doc
$ make html

Expected behavior

No error.

Your project

https://github.com/ssec/polar2grid/

Screenshots

No response

OS

Ubuntu

Python version

3.10

Sphinx version

5.0.0

Sphinx extensions

No response

Extra tools

No response

Additional context

No response

[djhoese]

I removed the .. include and still had issues with other ifconfig usage so the .. include isn't important.

[AA-Turner]

Hi David,

Is there a single file minimal reproducer? I assume this worked on 4.5.0?

A

[djhoese]

Yes it worked with older sphinx. I'll try to make a single file reproducer today.

[djhoese]

source/index.rst:

Home
====

.. ifconfig:: config_bool

    .. only:: not html

        `Google <https://www.google.com>`__

    `GitHub Repository <https://github.com/ssec/polar2grid>`__


.. ifconfig:: config_bool

    .. only:: not html

        `Google <https://www.google.com>`__

    `GitHub Repository <https://github.com/ssec/polar2grid>`__

source/conf.py

def setup(app):
    app.add_config_value("config_bool", False, "env")

extensions = ["sphinx.ext.ifconfig"]

Build command:

rm -rf build/*; sphinx-build -b html -d build/doctrees source build/html

It seems my use of .. only is maybe a problem. I noticed that if I removed the second ifconfig then it was fine so something about having them back to back mayber?

[djhoese]

Yes, if I add any normal text between the two ifconfig sections then it works.

Edit: typo

[djhoese]

Here's a simpler index.rst that triggers it:

Home
====

.. ifconfig:: config_bool

    `GitHub Repository <https://github.com/ssec/polar2grid>`__


.. ifconfig:: config_bool

    `GitHub Repository <https://github.com/ssec/polar2grid>`__

[AA-Turner]

Thanks David! I'll look into this now.

A

[djhoese]

If I put a comment .. a comment between them then it works too so that is at least a workaround if this is a difficult to fix bug.

And thanks for looking into it so quickly. Appreciated.

[AA-Turner]

Note for future self: self-contained script:

from pathlib import Path
import shutil

from sphinx.cmd.make_mode import run_make_mode

Path("conf.py").write_text('''\
extensions = ["sphinx.ext.ifconfig"]

def setup(app):
    app.add_config_value("config_bool", False, "env")
''', encoding="utf-8")

Path("index.rst").write_text('''\
.. ifconfig:: config_bool

    `GitHub Repository <https://github.com/ssec/polar2grid>`__

.. ifconfig:: config_bool

    `GitHub Repository <https://github.com/ssec/polar2grid>`__
''', encoding="utf-8")

shutil.rmtree("_build", ignore_errors=True)
run_make_mode(["html", ".", "_build"])

runs as python reproducer_10496.py

A

[AA-Turner]

The problem is in

sphinx/sphinx/ext/ifconfig.py

Lines 54 to 69 in 873d9f6

	for node in doctree.findall(ifconfig):
	try:
	res = eval(node['expr'], ns)
	except Exception as err:
	# handle exceptions in a clean fashion
	from traceback import format_exception_only
	msg = ''.join(format_exception_only(err.__class__, err))
	newnode = doctree.reporter.error('Exception occurred in '
	'ifconfig expression: \n%s' %
	msg, base_node=node)
	node.replace_self(newnode)
	else:
	if not res:
	node.replace_self([])
	else:
	node.replace_self(node.children)

specifically when the condition is false. Normally mutating a Docutils node tree whilst iterating (doctree.findall) is fine, but as we replace with an empty node, the second ifconfig node is skipped and not evaluated. The fix is to replace with a placeholder node, such as addnodes.meta.

A

[tk0miya]

Fixed by #10502.