From be805ee81544632b43479f31f8cb788142881066 Mon Sep 17 00:00:00 2001 From: JordanMG13 <91559220+JordanMG13@users.noreply.github.com> Date: Mon, 17 Aug 2026 16:45:49 -0500 Subject: [PATCH 1/5] Add sphinx-llm build failures fix Per: https://github.com/canonical/sphinx-stack/pull/622 --- docs/how-to/troubleshooting.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/how-to/troubleshooting.rst b/docs/how-to/troubleshooting.rst index e6672e9..5a708b8 100644 --- a/docs/how-to/troubleshooting.rst +++ b/docs/how-to/troubleshooting.rst @@ -100,3 +100,31 @@ For example: From there, you can make the version active again, which will make it visible in the web GUI, or change its slug. + +Sporadic build failures due to a "No such file or directory" error +------------------------------------------------------------------ + +If your Readthedocs builds are sporadically failing due to a file missing error, it is best to +first check the build output to make sure the issue isn't related to dependencies. + +Once you have verified this is not the case, you can double check your conf.py configuration. + +Possible causes +~~~~~~~~~~~~~~~ + +sphinx-llm by default creates a parallel process that touches build files while the main process +(or other extensions, like sphinx-tags) could still be using them. This can cause the missing +file error. + +Resolution +~~~~~~~~~~ + +*Please note that this workaround can cause your build times to grow rather large, +as the parallel nature of the normal config cuts build times considerably.* + +To fix this, simply tell sphinx-llm in your conf.py to not build in parallel: + +.. code-block:: python + + # Run sphinx-llm markdown generation sequentially to prevent race conditions + llms_txt_build_parallel = False From 923bcab9bd6742f757e9a300dcd97e08f42446d4 Mon Sep 17 00:00:00 2001 From: a-velasco Date: Fri, 18 Sep 2026 12:02:39 +0200 Subject: [PATCH 2/5] small formatting fixes --- docs/how-to/troubleshooting/build-errors.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/how-to/troubleshooting/build-errors.rst b/docs/how-to/troubleshooting/build-errors.rst index f5e8799..a2546c2 100644 --- a/docs/how-to/troubleshooting/build-errors.rst +++ b/docs/how-to/troubleshooting/build-errors.rst @@ -67,25 +67,25 @@ To fix the issue, try: Sporadic build failures due to a "No such file or directory" error ------------------------------------------------------------------ -If your Readthedocs builds are sporadically failing due to a file missing error, it is best to +If your Read the Docs builds are sporadically failing due to a file missing error, it is best to first check the build output to make sure the issue isn't related to dependencies. -Once you have verified this is not the case, you can double check your conf.py configuration. +Once you have verified this is not the case, you can double check your ``conf.py`` configuration. Probable cause ~~~~~~~~~~~~~~~ -sphinx-llm by default creates a parallel process that touches build files while the main process -(or other extensions, like sphinx-tags) could still be using them. This can cause the missing +The ``sphinx-llm`` extension by default creates a parallel process that touches build files while the main process +(or other extensions, like ``sphinx-tags``) could still be using them. This can cause the missing file error. Resolution ~~~~~~~~~~ -*Please note that this workaround can cause your build times to grow rather large, -as the parallel nature of the normal config cuts build times considerably.* +.. warning:: + Please note that this workaround can cause your build times to grow rather large, as the parallel nature of the normal config cuts build times considerably. -To fix this, simply tell sphinx-llm in your conf.py to not build in parallel: +To fix this, simply tell ``sphinx-llm`` in your ``conf.py`` to not build in parallel: .. code-block:: python From dd83e80374a0a265717289d6c778e328e3504f61 Mon Sep 17 00:00:00 2001 From: a-velasco Date: Fri, 18 Sep 2026 12:05:52 +0200 Subject: [PATCH 3/5] add 'PRs' to spelling exceptions --- docs/.custom_wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index d7cbd1c..b7c63d7 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -70,6 +70,7 @@ GitHub Sphinx URL PR +PRs Read the Docs Spread landscape From ea5fb077e845f2165105ee375cbc7c6ac3d28033 Mon Sep 17 00:00:00 2001 From: JordanMG13 <91559220+JordanMG13@users.noreply.github.com> Date: Fri, 18 Sep 2026 09:31:03 -0500 Subject: [PATCH 4/5] Apply batched suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Grammar nit-picks Co-authored-by: Robert Krátký --- docs/how-to/troubleshooting/build-errors.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how-to/troubleshooting/build-errors.rst b/docs/how-to/troubleshooting/build-errors.rst index a2546c2..198078e 100644 --- a/docs/how-to/troubleshooting/build-errors.rst +++ b/docs/how-to/troubleshooting/build-errors.rst @@ -67,10 +67,10 @@ To fix the issue, try: Sporadic build failures due to a "No such file or directory" error ------------------------------------------------------------------ -If your Read the Docs builds are sporadically failing due to a file missing error, it is best to +If your Read the Docs builds are sporadically failing due to a file missing error, first check the build output to make sure the issue isn't related to dependencies. -Once you have verified this is not the case, you can double check your ``conf.py`` configuration. +Once you have verified this is not the case, double check your ``conf.py`` configuration. Probable cause ~~~~~~~~~~~~~~~ @@ -83,9 +83,9 @@ Resolution ~~~~~~~~~~ .. warning:: - Please note that this workaround can cause your build times to grow rather large, as the parallel nature of the normal config cuts build times considerably. + Note that this workaround can cause your build times to grow, as the parallel nature of the normal config cuts build times considerably. -To fix this, simply tell ``sphinx-llm`` in your ``conf.py`` to not build in parallel: +To fix this, tell ``sphinx-llm`` in your ``conf.py`` to not build in parallel: .. code-block:: python From 457e99023386e4ca843541b754a94540b0807e08 Mon Sep 17 00:00:00 2001 From: JordanMG13 <91559220+JordanMG13@users.noreply.github.com> Date: Fri, 18 Sep 2026 10:07:20 -0500 Subject: [PATCH 5/5] Update docs/how-to/troubleshooting/build-errors.rst Consolidate title of section Co-authored-by: JJ Coldiron --- docs/how-to/troubleshooting/build-errors.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/troubleshooting/build-errors.rst b/docs/how-to/troubleshooting/build-errors.rst index 198078e..c993e2e 100644 --- a/docs/how-to/troubleshooting/build-errors.rst +++ b/docs/how-to/troubleshooting/build-errors.rst @@ -64,8 +64,8 @@ To fix the issue, try: * Restricting problem packages to recent versions (using ``package~=version``) * Using a constraints file -Sporadic build failures due to a "No such file or directory" error ------------------------------------------------------------------- +Sporadic "No such file or directory" errors +------------------------------------------- If your Read the Docs builds are sporadically failing due to a file missing error, first check the build output to make sure the issue isn't related to dependencies.