Server perpetually restarts after rebuilding documentation

[JulianOrteil]

Describe the bug

context/problem Launching sphinx-autobuild from tox (in conjunction with tox-conda) results in the server continuously relaunching. Specifying
--no-initial results in the server launching as expected until it detects a change and rebuilds the documentation, then this issue persists again. Also, CTRL+C is not responsive, I have to kill the terminal to quit this issue.

expectation This not to occur.

Reproduce the bug

1. Setup and create an Anaconda environment, or at least have the program installed and on PATH
2. Install tox and tox-conda: pip install tox tox-conda
3. Create a tox.ini file with something similar to the following:

[testenv:autodocs]
description =
    Invoke sphinx-autobuild to hot reload docs changes
deps =
    sphinx>=3.2.1
    furo
    sphinx-copybutton
    sphinx-autobuild
commands =
    # Add --no-initial to see that described behavior
    sphinx-autobuild docs docs/_build/html

4. Launch with tox -e autodocs

List your environment

Python: 3.9.12 Windows 10 Anaconda env, likely not necessary Other tools, see above

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[theletterf]

Having the same issue, but within a Docker container.

[lwasser]

i'm actually running into this same issue as well. i'm just running it locally and/or using hatch scripts. once i make a change, it continues to rebuild and rebuild.

so i can run it outside of hatch and get the same result

sphinx-autobuild docs/ docs/_build

output as expected

then i make a change to any page in the build and it starts to spin. I can not sure what is causing this but i see this behavior in this pr. i am open to suggestions!!

this is my envt

➜ conda list
# packages in environment at /Users/leahawasser/mambaforge/envs/pyospackage:
#
# Name                    Version                   Build  Channel
accessible-pygments       0.0.5                    pypi_0    pypi
alabaster                 0.7.16                   pypi_0    pypi
anyio                     4.4.0                    pypi_0    pypi
astroid                   3.2.2                    pypi_0    pypi
babel                     2.15.0                   pypi_0    pypi
beautifulsoup4            4.12.3                   pypi_0    pypi
bzip2                     1.0.8                h93a5062_5    conda-forge
ca-certificates           2024.6.2             hf0a4a13_0    conda-forge
certifi                   2024.6.2                 pypi_0    pypi
charset-normalizer        3.3.2                    pypi_0    pypi
click                     8.1.7                    pypi_0    pypi
colorama                  0.4.6                    pypi_0    pypi
docutils                  0.21.2                   pypi_0    pypi
exceptiongroup            1.2.1                    pypi_0    pypi
h11                       0.14.0                   pypi_0    pypi
idna                      3.7                      pypi_0    pypi
imagesize                 1.4.1                    pypi_0    pypi
jinja2                    3.1.4                    pypi_0    pypi
libblas                   3.9.0           22_osxarm64_openblas    conda-forge
libcblas                  3.9.0           22_osxarm64_openblas    conda-forge
libcxx                    17.0.6               he7857fb_1    conda-forge
libffi                    3.4.2                h3422bc3_5    conda-forge
libgfortran               5.0.0           13_2_0_hd922786_3    conda-forge
libgfortran5              13.2.0               hf226fd6_3    conda-forge
liblapack                 3.9.0           22_osxarm64_openblas    conda-forge
libopenblas               0.3.27          openmp_h6c19121_0    conda-forge
libsqlite                 3.45.2               h091b4b1_0    conda-forge
libzlib                   1.2.13               h53f4e23_5    conda-forge
llvm-openmp               18.1.8               hde57baf_0    conda-forge
markdown-it-py            3.0.0                    pypi_0    pypi
markupsafe                2.1.5                    pypi_0    pypi
mdit-py-plugins           0.4.1                    pypi_0    pypi
mdurl                     0.1.2                    pypi_0    pypi
myst-parser               3.0.1                    pypi_0    pypi
ncurses                   6.4                  h463b476_2    conda-forge
numpy                     2.0.0           py310h52bbd9b_0    conda-forge
openssl                   3.3.1                hfb2fe0b_0    conda-forge
packaging                 24.1                     pypi_0    pypi
pandas                    2.2.2           py310h2216879_1    conda-forge
pip                       24.0               pyhd8ed1ab_0    conda-forge
pydata-sphinx-theme       0.15.4                   pypi_0    pypi
pygments                  2.18.0                   pypi_0    pypi
pyospackage               0.1                      pypi_0    pypi
python                    3.10.13         h2469fbe_1_cpython    conda-forge
python-dateutil           2.9.0              pyhd8ed1ab_0    conda-forge
python-tzdata             2024.1             pyhd8ed1ab_0    conda-forge
python_abi                3.10                    4_cp310    conda-forge
pytz                      2024.1             pyhd8ed1ab_0    conda-forge
pyyaml                    6.0.1                    pypi_0    pypi
readline                  8.2                  h92ec313_1    conda-forge
requests                  2.32.3                   pypi_0    pypi
setuptools                69.2.0             pyhd8ed1ab_0    conda-forge
six                       1.16.0             pyh6c4a22f_0    conda-forge
sniffio                   1.3.1                    pypi_0    pypi
snowballstemmer           2.2.0                    pypi_0    pypi
soupsieve                 2.5                      pypi_0    pypi
sphinx                    7.3.7                    pypi_0    pypi
sphinx-autoapi            3.1.2                    pypi_0    pypi
sphinx-autobuild          2024.4.16                pypi_0    pypi
sphinx-copybutton         0.5.2                    pypi_0    pypi
sphinx-design             0.6.0                    pypi_0    pypi
sphinxcontrib-applehelp   1.0.8                    pypi_0    pypi
sphinxcontrib-devhelp     1.0.6                    pypi_0    pypi
sphinxcontrib-htmlhelp    2.0.5                    pypi_0    pypi
sphinxcontrib-jsmath      1.0.1                    pypi_0    pypi
sphinxcontrib-qthelp      1.0.7                    pypi_0    pypi
sphinxcontrib-serializinghtml 1.1.10                   pypi_0    pypi
starlette                 0.37.2                   pypi_0    pypi
tk                        8.6.13               h5083fa2_1    conda-forge
tomli                     2.0.1                    pypi_0    pypi
typing-extensions         4.12.2                   pypi_0    pypi
tzdata                    2024a                h0c530f3_0    conda-forge
urllib3                   2.2.2                    pypi_0    pypi
uvicorn                   0.30.1                   pypi_0    pypi
watchfiles                0.22.0                   pypi_0    pypi
websockets                12.0                     pypi_0    pypi
wheel                     0.42.0             pyhd8ed1ab_0    conda-forge
xz                        5.2.6                h57fd34a_0    conda-forge

[lwasser]

I tried removing some of the build extensions like autoapi. but i'm still getting this issue! if anyone has a suggestion of things I could try to troubleshoot I'm game to try to figure this out. i'm just not sure where to begin to troubleshoot this.

[trallard]

Another data point: we have been experiencing the same issue with sphinx-autobuild and stb (which uses sphinx-autobuild under the hood) while working on PyData Sphinx theme.

IIRC we were using sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b so we could ignore some files (translation files included) like so

But am seeing this infinite reload too atm on both even if using sphinx-autobuild -a docs docs/_build/html --watch src/pydata_sphinx_theme --open-browser --ignore=**/locale/**,**/api/**,**/_build/**,.jupyterlite.doit.db `

I might have a look at the internals here to dive into the --watch logic and see if I can spot anything out of place.

[AA-Turner]

See 1743a4370869e3338c84ddb8778b3fa0b811b23d.

You can also use WATCHFILES_DEBUG to log the raw changes: https://watchfiles.helpmanual.io/api/watch/?h=WATCHFILES_DEBUG#watchfiles.watch

A

[lwasser]

I wanted to also note another data point that i just saw last night / today! I have a sphinx build that using myst-nb. I had a never-ending loop happening that was due to a notebook that mistakenly had an empty top cell. Removing it stopped the autobuild repetition. this is separate from what I've seen in stravalib. It does seem like a bug in the build will cause the build to try and retry. i haven't used watch before but i'll look into it. it seems like the fix is some bug in the sphinx-build that is not clear in the build output.

[AA-Turner]

@lwasser what's the output when using WATCHFILES_DEBUG? You can also use sphinx-autobuild 2024.10.02 which will display which files triggered the rebuild.

[lwasser]

That information alone (which files triggered it) is useful. Thank you so much. @AA-Turner !!