Unable to build Furo docs - getting exception: '_static/styles/furo.css' is not in list

[datajoely]

Hello I work on the Kedro project and I'm trying to see if we could switch our docs to furo but I keep getting the error below - any ideas what I could do to fix it?

  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/events.py", line 110, in emit
    results.append(listener.handler(self.app, *args))
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/furo/__init__.py", line 154, in _html_page_context
    _add_asset_hashes(
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/furo/__init__.py", line 139, in _add_asset_hashes
    index = static.index("_static/" + asset)
ValueError: '_static/styles/furo.css' is not in list

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/application.py", line 346, in build
    self.builder.build_all()
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 259, in build_all
    self.build(None, summary=__('all source files'), method='all')
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 360, in build
    self.write(docnames, list(updated_docnames), method)
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 534, in write
    self._write_serial(sorted(docnames))
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 544, in _write_serial
    self.write_doc(docname, doctree)
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 603, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 1016, in handle_page
    newtmpl = self.app.emit_firstresult('html-page-context', pagename,
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/application.py", line 467, in emit_firstresult
    return self.events.emit_firstresult(event, *args,
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/events.py", line 127, in emit_firstresult
    for result in self.emit(name, *args, allowed_exceptions=allowed_exceptions):
  File "/Users/$user/miniconda3/envs/kedro-dev/lib/python3.8/site-packages/sphinx/events.py", line 117, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function _html_page_context at 0x7fdf0e95d700> for event 'html-page-context' threw an exception (exception: '_static/styles/furo.css' is not in list)

Extension error:
Handler <function _html_page_context at 0x7fdf0e95d700> for event 'html-page-context' threw an exception (exception: '_static/styles/furo.css' is not in list)

If I inspect furo/__init__.py:136 at runtime the "furo.css" file doesn't exist in the list:

[pradyunsg]

How did you install Furo?

[pradyunsg]

That looks a bit more involved than I'd like. My guess is that it is a configuration option/hook in your file that's messing stuff up.

Can you try commenting out basically all of your configuration file and try adding things in (bisected will be easiest) to find out what is involved? sphinx-autobuild should make that fairly not-painful to do.

[datajoely]

Thank you - thought as much, I was mostly asking just in-case this was a common error with a simple solution.

[pradyunsg]

I haven't seen this before, no.

[bertiewooster]

Hi @datajoely @pradyunsg was there a resolution to this? I'm getting the same error trying to use furo for SymPy. Here's the process:

1. Add furo to doc/requirements.txt
2. In the doc folder, build dockerfile using docker build -f Dockerfile.htmldoc -t sympy_htmldoc . where Dockerfile.htmldoc is:

FROM python:3.8.12-slim-buster

RUN apt-get update
RUN apt-get install -y make librsvg2-bin imagemagick graphviz git

COPY requirements.txt /tmp
RUN pip install --upgrade pip
RUN pip install -r /tmp/requirements.txt

CMD cd /sympy/doc; make html

3. Build documentation using docker run --rm -v /absolute/path/to/SYMPY_ROOT:/sympy sympy_htmldoc

Error is:

Extension error (furo):
Handler <function _html_page_context at 0x7f674f1f6a60> for event 'html-page-context' threw an exception (exception: '_static/styles/furo.css' is not in list)
make: *** [Makefile:60: html] Error 2

[pradyunsg]

Can you run sphinx-build with --verbose?

[pradyunsg]

Figured out why this is happening! Unset html_style that is set in your conf.py file.

[pradyunsg]

The problematic line in the sympy configuration: https://github.com/sympy/sympy/blob/b0b66d5511575eda9f0e3c7cc048b7bf63a85706/doc/src/conf.py#L133

[pradyunsg]

Released with a better error message.

[pradyunsg]

576b68e

[datajoely]

Thank you!

[bertiewooster]

@pradyunsg That worked--thanks for isolating the problem! I have to say that the furo version of the SymPy docs looks great already--haven't even investigated doing any other tweaking to our existing conf.py.

[doyled-it]

I'm still getting this error. When I went in to debug this, I checked the value for all the c.filenames seen in this check:

['_static/pygments.css', '_static/styles/furo.css?digest=369552022d0b975c8e74270ce6eabe0fb7978f24', '_static/graphviz.css', '_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e']

It looks like you're appending an asset hash and it's missing it when it goes to check that list?

[pradyunsg]

Please open a new discussion, with a reproducer for the behaviour you're seeing. :)

[doyled-it]

Thanks for responding. I opened one here.

[arxyzan]

@doyled-it Do you also have sphinx_rtd_theme installed along with furo? I had this problem when trying to deploy my docs on github pages and after deleting sphinx_rtd_theme from the requirements, the problem was solved.

[mcflugen]

@arxyzan Thank you! This was exactly my problem. You saved me so much time!

[doyled-it]

Hmm, that didn't end up working for me. I'm only experiencing this issue after doing a poetry update command last week.