llms.txt generation fails silently if markdown build fails #27
Description
Currently the way the llms.txt generation works is at the end of the Sphinx build a second full sphinx build is triggered using the markdown builder. Then the generated markdown files are copied into the build output directory for the main sphinx build. Finally these files are aggregated into a markdown sitemap in llms.txt and full dump in llms-full.txt.
However, if the second sphinx build fails for some reason (like an extension doesn't support the markdown builder) it just fails silently. The build appears to succeed but no markdown files are generated and llms.txt and llms-full.txt never get created.
Reproducer:
- Make a base sphinx project
mkdir -p /tmp/sphinx-fail-demo
cd /tmp/sphinx-fail-demo
sphinx-quickstart --sep -p demo -a "Demo" -r "" -l "en"- Make a new extensions directory
mkdir extensions- Make a new extension that only works with HTML and not markdown
# extensions/broken_extension.py
def fail_on_markdown(app, exception):
if app.builder.name == "markdown":
raise ValueError("Markdown builder is not supported")
def setup(app):
"""Set up the Sphinx extension."""
app.connect("build-finished", fail_on_markdown)- Configure
source/conf.pyto usesphinx-llmand the broken extension
# source/conf.py
...
import sys, os
sys.path.insert(0, os.path.abspath("../extensions"))
extensions = ["sphinx_llm.txt", "broken_extension"]
...- Build the docs
$ make html
Running Sphinx v7.4.7
loading translations [en]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files... done
copying extra files... done
copying assets: done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
Generating markdown files for LLMs...- Inspect the built files and note that
index.html.md,llms.txtandllms-full.txtare missing
$ ls build/html
_sources _static genindex.html index.html objects.inv search.html searchindex.js- If you run
make markdownyou can clearly see the failure that is not being caught
$ make markdown
Running Sphinx v7.4.7
loading translations [en]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [markdown]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying assets: done
writing output... [100%] index
Markdown generation only works with HTML builders (html or dirhtml)
WARNING: Skipping markdown generation due to build error
Extension error (broken_extension):
Handler <function fail_on_markdown at 0x1207063e0> for event 'build-finished' threw an exception (exception: Markdown builder is not supported)
make: *** [markdown] Error 2