Unclear error message: TypeError: unsupported operand type(s) for /: 'str' and 'str'

sylvestre commented 1 week ago

Describe the bug

Trying to upgrade Firefox doc to version 8.1.2, I am getting this exception. it could be catch to provide a better error message. I guess it is because a file is missing


# Last messages:
#   genindex
#   py-modindex
#   fait
#   Écriture des pages additionnelles...
#   search
#   fait
#
#   copie des images... [  0%]
#   accessible/fxview.jpg
#

# Traceback:
Traceback (most recent call last):
  File "/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 766, in copy_image_files
    self.srcdir / src,
    ~~~~~~~~~~~~^~~~~
TypeError: unsupported operand type(s) for /: 'str' and 'str'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx/cmd/build.py", line 514, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx/application.py", line 381, in build
    self.builder.build_update()
  File "/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 358, in build_update
    self.build(
  File "/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 440, in build
    self.finish()
  File "/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 672, in finish
    self.finish_tasks.add_task(self.copy_image_files)
  File "/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx/util/parallel.py", line 42, in add_task
    res = task_func()
          ^^^^^^^^^^^
  File "/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 772, in copy_image_files
    __("cannot copy image file '%s': %s"), self.srcdir / src, err
                                           ~~~~~~~~~~~~^~~~~
TypeError: unsupported operand type(s) for /: 'str' and 'str'

How to Reproduce

Quite complex for now

Environment Information

# Loaded extensions:
#   sphinx.ext.mathjax (8.1.2)
#   alabaster (1.0.0)
#   sphinxcontrib.applehelp (2.0.0)
#   sphinxcontrib.devhelp (2.0.0)
#   sphinxcontrib.htmlhelp (2.1.0)
#   sphinxcontrib.serializinghtml (2.0.0)
#   sphinxcontrib.qthelp (2.0.0)
#   myst_parser (4.0.0)
#   sphinx.ext.autodoc.preserve_defaults (8.1.2)
#   sphinx.ext.autodoc.type_comment (8.1.2)
#   sphinx.ext.autodoc.typehints (8.1.2)
#   sphinx.ext.autodoc (8.1.2)
#   sphinx.ext.autosectionlabel (8.1.2)
#   sphinx.ext.doctest (8.1.2)
#   sphinx.ext.graphviz (8.1.2)
#   sphinx.ext.napoleon (8.1.2)
#   sphinx.ext.todo (8.1.2)
#   mozbuild.sphinx (unknown version)
#   sphinx_js (unknown version)
#   sphinxcontrib.jquery (4.1)
#   sphinxcontrib.mermaid (8.1.2)
#   sphinx_copybutton (0.5.2)
#   sphinx_markdown_tables (<module 'sphinx_markdown_tables.__version__' from '/home/sylvestre/.mozbuild/srcdirs/mozilla-unified.hg-667bd89df37b/_virtualenvs/docs/lib/python3.12/site-packages/sphinx_markdown_tables/__version__.py'>)
#   sphinx_design (0.6.1)
#   bzlink (unknown version)

Sphinx extensions

No response

Additional context

No response

AA-Turner commented 1 week ago

@sylvestre are you able to run with --pdb or insert a statement to print(f'{self.srcdir=}')?

srcdir should be a _StrPath instance, I wonder if one of your extensions is overwriting it to be a str, which would cause the TypeError you're seeing.

We do have test converage for this particular warning, so I don't think it's an issue with Sphinx in the first instance.

An easy reproduction case would be a sample index.rst:

Test
====

.. image:: test.png

and your current conf.py with the following added:

from pathlib import Path

IMG_PATH = Path('test.png')

def handler(app):
    assert IMG_PATH.exists()
    IMG_PATH.unlink()
    return []

def setup(app):
    IMG_PATH.touch()
    app.connect('html-collect-pages', handler)

When running this locally (sphinx-build -M html . build -T) I get the expected warning and no TypeError -- if you are getting the TypeError, can you try incrementally removing your extensions until no error occurs.

A

sylvestre commented 1 week ago

Indeed, seems to be an str:

(Pdb) print(f'{self.srcdir=}')
self.srcdir='/home/sylvestre/dev/mozilla/mozilla-unified.hg/obj-x86_64-pc-linux-gnu/docs/html/_staging'

electric-coder commented 1 week ago

@AA-Turner I'm not an expert but from reading thousands of threads on SO this segment to me is synonymous to trouble:

python3.12/site-packages

@sylvestre I'm not a Linux user but the above suggests you've installed Sphinx to a Python base installation (the kind that's a default and comes pre-installed with an OS)? Both in Windows and Linux this is known to cause inexplicable problems and a solution might be to install Sphinx to a clean venv and activate it to build the docs. Otherwise Python installations that aren't clean can be non-standard and cause all kinds of problems.

sphinx-doc / sphinx