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

[sylvestre]

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]

@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]

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]

@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.

[rtobar]

We had this same issue in https://github.com/python/python-docs-es/. It turns out it was our conf.py file where we were re-defining app.srcdir to be a string rather than a Path. I've never gone deep into sphinx's API documentation, but neither there nor in the CHANGELOG (we went from 7.2.4, where it was working, to 8.1.3 where it failed) could I find a reference to this property's type. Related PR is python/python-docs-es#2875.

[AA-Turner]

We could probably add getters/setters to raise warnings.

@rtobar what was your use-case for changing srcdir? We assume it is immutable internally, I think.

A

[rtobar]

@AA-Turner thanks for the quick reply.

In our case at https://github.com/python/python-docs-es/ (Spanish translation of the Python documentation) we have the following layout:

• Root directory with a tree of .pofiles
• A cpython submodule pointing to the version of CPython version we're translating
• A conf.py file in the root directory with Sphinx configuration imports everything from cpython/Doc/conf.py, tweaks a few things, and changes app.srcdir at setup time to point to cpython/Doc.

I'm not really familiar with how and why this setup came to be, as well as whether this is aligned with best practices for managing translation projects, so I'd be more than happy to listen for some advice.

It seems that the Firefox folks might be on the same boat, re-defining app.srcdir: https://searchfox.org/mozilla-central/source/python/mozbuild/mozbuild/sphinx.py#293

[AA-Turner]

Current master now enforces that {app,builder,env}.{conf,doctree,out,src}dir is a _StrPath, and converts strings to _StrPath when set.

We don't currently warn on this use-case, perhaps we should? But we could add this later once we use Path rather than _StrPath.

A