Sphinx extension error (sphinxprettysearchresults): for event 'build-finished', error "exception: name 'unicode' is not defined"

[Alex-TheWriter]

Describe the bug

In my Sphinx project (details are given below), when trying to generate the output HTML code using the "sphinx-build -E" command, I get the following persistent error: "Extension error (sphinxprettysearchresults): Handler <function build_search_snippets at 0x0000022451ACBF60> for event 'build-finished' threw an exception (exception: name 'unicode' is not defined)".

How to Reproduce

I enter the following:
...\root\myrepo>sphinx-build -E ...\root\myrepo\en ...\root\myrepo-build\output\en

I get the following:

Running Sphinx v7.2.6

…\Python\Lib\site-packages\sphinxcontrib\images.py:32: RemovedInSphinx80Warning: The alias' sphinx.util.status_iterator' is deprecated, use 'sphinx.util.display.status_iterator' instead. Check CHANGES for Sphinx API modifications.

from sphinx.util import status_iterator

Initiated sphinxcontrib-images backend: sphinxcontrib_images_lightbox2.lightbox2:LightBox2

building [mo]: targets for 0 po files that are out of date

writing output...

building [html]: targets for 925 source files that are out of date

updating environment: [new config] 925 added, 0 changed, 0 removed

reading sources... [100%] usd_hydra/hydra

Downloading remote images...

Copying static files for sphinxcontrib-images...[100%] lightbox2-customize/jquery-noconflict.js

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... [ 0%] amd_renderstudio/about

Extension error (sphinxprettysearchresults):

Handler <function build_search_snippets at 0x0000010F10D4FF60> for event 'build-finished' threw an exception (exception: name 'unicode' is not defined)

Environment Information

Platform:              win32; (Windows-10-10.0.19045-SP0)
Python version:        3.12.1 (tags/v3.12.1:2305ca5, Dec  7 2023, 22:03:25) [MSC v.1937 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.20.1
Jinja2 version:        3.1.3
Pygments version:      2.17.2

Sphinx extensions

The most recent versions of:
karma_sphinx_theme
sphinxprettysearchresults
sphinxcontrib-images
sphinx_sitemap
sphinxcontrib-contentui

Additional context

My PC is under Windows 10.

[jdillard]

I'm not sure you needed to create a duplicate issue, the sphinxprettysearchresults repo seems to be the correct place: sphinx-contrib/sphinx-pretty-searchresults#34

[electric-coder]

@jdillard I also noticed that but the last update in the sphinx-pretty-searchresults repository was about a year ago, so I think it's reasonable to cross-post here since the other repository seem to be inactive atm.

[jayaddison]

@Alex-TheWriter could you share what version of Sphinx you're using?

The reason I ask: if you have upgraded (or can do) to Sphinx v2.0.0 or later, then you should be able to remove sphinx-pretty-searchresults.

(sphinx-pretty-searchresults provides a workaround for bug #1618 in Sphinx, and that bug was fixed within Sphinx itself from v2.0.0 and beyond)

[jayaddison]

Ah: sometimes I get carried away doing the research, instead of reading the details... I see that you're on version 7.2.6 - so I think it should indeed be safe to remove sphinx-pretty-searchresults from your Sphinx extensions, and then these errors should disappear.

[jayaddison]

@jdillard @electric-coder if my above explanation seems correct to you too: perhaps we could add a note to the sphinx-pretty-searchresults.git repository to say that it's no-longer-required?

(or, if we wanted to do something more awareness-raising, then perhaps a new release that adds an upper-bound Sphinx version dependency. doing that kind of thing apparently makes some Bazel builds unhappy, but on balance I think getting the message out that the extension is no longer required is probably a greater benefit)

[electric-coder]

@jayaddison the last paragraph sums things up "in a nutshell"...

1. add a note to the sphinx-pretty-searchresults.git repository to say that it's no-longer-required?

   Absolutely! Looking at the repository's README.rst no one would guess the extension's functionality has since been integrated into Sphinx core. Everything in the sphinx-contrib collection has high visibility and by not including an explicit notice at the top of sphinx-pretty-searchresults's repository users are left thinking they're potentially missing out on functionality when in fact they've already been enjoying it in recent Sphinx releases!

2. then perhaps a new release that adds an upper-bound Sphinx version dependency

   Also an excellent idea! It will save a number of users the trouble of being left to wonder about this issue.

3. doing that kind of thing apparently makes some Bazel builds unhappy

   I don't know anything about Bazel but the first 2 points are the right approach.

[Alex-TheWriter]

Thank you, @jayaddison, @electric-coder, and @jdillard, for your comments and suggestions on how to correct this and other errors of Sphinx.

1. To remove the extension, I entered the following command:
   pip uninstall sphinxprettysearchresults
   Uninstalling sphinxprettysearchresults-0.3.5:
   Would remove:
   d:...\python\lib\site-packages\sphinxprettysearchresults-0.3.5.dist-info*
   d:...\python\lib\site-packages\sphinxprettysearchresults*
   Proceed (Y/n)? Y
   ...

2. After I tried once again to generate HTML output for my website using the same
   `sphinx-build -E ...',
   I got the following warning and then, for the first new *.rst file I added to the repo, the following error:
   Running Sphinx v7.2.6
   WARNING: while setting up extension sphinxprettysearchresults: extension 'sphinxprettysearchresults' has no setup() function; is it really a Sphinx extension module?
   ...
   ...
   THEME ERROR:
   An error happened in rendering the page amd_renderstudio/about.
   Reason: UndefinedError("'style' is undefined")

QUESTIONS: Was sphinxprettysearchresults properly removed (if the next command tries to set it up again)?
Why "UndefinedError("'style' is undefined")"?! Is this because of the usage of style key which has been removed in Python 7+?

[electric-coder]

@Alex-TheWriter I think it means that in your conf.py where the extensions variable is you have to delete that line with the "sphinxprettysearchresults" inclusion, so for example:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    # "sphinxprettysearchresults"  # Remove this line!
    "sphinx.ext.extlinks",
    "sphinx.ext.intersphinx",
}

[Alex-TheWriter]

Thank you, @electric-coder, the warning about the extension is no longer seen when running sphinx-build -E..., but the error which prevents Sphinx from generating the output HTML is still there (below). sphinx-build -E... worked in some earlier versions of Python (3.6+) but now we are incompatible with Sphinx 7.2.6. Is this due to the usage of style key which has been removed?
When Sphinx starts rendering the first of the newly added RST files, it fails:
"An error happened in rendering the page amd_renderstudio/about.
Reason: UndefinedError("'style' is undefined")"

[jdillard]

I'm pretty sure you need to open an issue on karma_sphinx_theme for that one, as this line looks to be the issue. They will need to support Sphinx 7.

You can see some explanation here of people having that issue with a different theme: readthedocs/sphinx_rtd_theme#1465

edit: Someone already opened a PR to fix that: AccentDesign/karma_sphinx_theme#6

[electric-coder]

@Alex-TheWriter the excellent research from @jdillard shows the problem now is an incompatibility between the current Sphinx version and the theme you are using, notice the karma_sphinx_theme was last updated 4 years ago...

I would recommend looking through the Sphinx themes gallery and choosing an up-to-date theme that's being actively maintained. Currently three themes are often recommend: furo theme, the PyData theme or the Sphinx book theme because they're well supported and have a large user base. Depending on what you want there are some more minimal themes that likely also work well. Check the theme's GitHub repositories for recent activity.